Create a Web service with Ruby on Rails for integration with WebSphere Process Server

Invoking SCA components from Ruby clients

Learn how to use a Web service to facilitate the communication between a Ruby on Rails client and an SCA component running on WebSphere® Process Server. You can see how to expose the SCA component as a service, followed by the steps required to generate the Ruby client that will invoke the service. This article does not cover all of the details surrounding Ruby on Rails programming or SCA development; the focus is on the details required for the integration of a WebSphere Process Server with Ruby on Rails Web service clients.


Terrence White (, Advisory IT Specialist, IBM

Terrence White is an Advisory I/T Specialist from IBM Global Services. He is currently working with the Enterprise Component Business Architecture team, with a focus on Web services and business process development using process choreography.

developerWorks Contributing author

09 August 2007

Also available in Chinese


WebSphere Process Server is an IBM flagship business integration product that supports the runtime activities in the SOA lifecycle. WebSphere Process Server is built on top of the WebSphere Enterprise Service Bus product, and it provides many additional functions, including support for BPEL-based processes, business state computers, business rules, and human tasks. The Service Component Architecture (SCA) provides the basic programming model for WebSphere Process Server and WebSphere Enterprise Service Bus. SCA describes all integration artifacts as service components with well-defined interfaces.

Ruby is a dynamically typed, interpreted, object-oriented scripting language. It is known for its straightforward syntax and ease of use. Rails is a powerful add-on to the Ruby programming language, providing a dynamic framework for the development of database-driven Web applications. Ruby on Rails is a Web application framework that uses the model-view-controller architectural pattern for organizing applications. It is built on two solid principles:

  • Convention over configuration
  • Don't repeat yourself (DRY)

Convention over configuration means that a developer needs to conform to all of the naming conventions Rails uses, avoiding custom configurations. This tradeoff allows the framework to drastically speed up application development. DRY means that information is located in a single place, allowing the framework to standardize the organization of the project. These principles work together to allow the framework to speed up the development of the applications by making key assumptions about the artifacts that compose the application.

For example, if you have an object in Rails called LineItem, Rails assumes that there is a corresponding database table called line_items to store the data. Therefore, the developer does not have to repeat work by providing a mapping to the framework telling it where the persistence store is for the object. In order for this approach to work, the developer follows the proper naming scheme for the object and table names. When the proper naming conventions are followed, Rails can generate the DDL scripts for creating the tables in the database, thus putting the development cycle on fast-forward.

This article demonstrates the integration of a Web service client running in the Ruby on Rails framework with an SCA component deployed into WebSphere Process Server.

Exposing the SCA component as a Web service

This section describes how to create a simple SCA component and expose it as a Web service. You should have WebSphere Integration Developer installed (see Resources).

Create the SCA module

Open WebSphere Integration Developer, and use the context menu to create a new SCA module called TestModule to hold the component.

Figure 1. Context menu for module creation
Context menu for module creation

Create a new SCA component

Complete the following steps to create a new SCA component.

  1. Create an interface for the component by downloading the TestServiceData.xsd file and drag-and-dropping it onto the Data Types folder.
    Figure 2. Drag and drop the TestServiceData.xsd file
    Drag and drop the TestServiceData.xsd file
  2. Right-click interfaces, and create a new interface called TestServiceInterface.
    Figure 3. Context menu for interface creation
    Context menu for interface creation
  3. Create a two-way operation called callTestService, selecting the appropriate message types, as shown in Figure 4.
    Figure 4. Completed service interface
    Completed service interface
  4. Open the assembly diagram, if it is not already open, and drag a new SCA component with no implementation type onto the canvas. Rename the component TestService.
    Figure 5. Context menu for SCA component creation
    Context menu for SCA component creation
  5. Use the context menu for the component to associate the interface with the component.
    Figure 6. Context menu for the interface assignment
    Context menu for the interface assignment
  6. Select the Show WSDL radio button, select TestServiceInterface, and click Apply.
    Figure 7. Selecting TestServiceInterface
    Selecting TestServiceInterface
    WebSphere Integration Developer supports the following implementation types for SCA components:
    • BPEL
    • State machine
    • Business rule
    • Human task
    • Java™

    Next, you can create a simple Java component and expose it with a Web service binding. However, you can use any supported WebSphere Integration Developer implementation type.

  7. Right-click on the SCA component, and generate a Java implementation for the component.
    Figure 8. Context menu for Java implementation generation
    Context menu for Java implementation generation
    Notice that WebSphere Integration Developer has generated a callTestService method to match the operation that you created in the service interface.
  8. Add the following code to the callTestService method.
    Listing 1. Sample code for callTestService method
      public DataObject callTestService(DataObject input) {
      String firstName  = input.getString("firstName");
      String middleName = input.getString("middleName");
      String lastName   = input.getString("lastName");
      String outputStr  = "Hello " + firstName + " " + middleName + " " + lastName + 
                          ", I am WebSphere Process Server!"; 
      ServiceManager sm = new ServiceManager();
      BOFactory bof     = (BOFactory)(sm.locateService("com/ibm/websphere/bo/BOFactory"));
      DataObject output = bof.create("http://TestModule/Data", "TestServiceOutput");
      output.setString("returnMessage", outputStr);
      return output;

    The code takes the first, middle, and last names as input, and it creates a hello message from the process server and sends it back to Ruby on Rails. The next section describes how that is done.

Expose the component as a Web service

  1. Drag an export component onto the canvas, and wire it to the Java component. Select OK when prompted.
    Figure 9. Context menu for the export component
    Context menu for the export component
    Figure 10. Wiring the export to the component
    Wiring the export to the component
  2. Use the context menu of the export component to generate a SOAP/HTTP Web service binding.
    Figure 11. Generating the Web service binding
    Generating the Web service binding
    Figure 12. Selecting the SOAP protocol
    Selecting the SOAP protocol
  3. Notice the new entry under Web Service Ports.
    Figure 13. Generated Web service port
    Generated Web service port

Generating the Ruby on Rails Web service client

Install Ruby on Rails

Locate the Ruby on Rails installation packages at the Ruby Web site (see Resources) Follow the instructions in this section to perform the installation.

Install SOAP4R

This article uses a Ruby package called SOAP4R to generate the Ruby client code required to invoke the Web service running on WebSphere Process Server.

Ruby on Rails utility commands

This article uses various utility scripts in the Ruby on Rails environment. After installing Rails, ensure that the Ruby bin directory is set on the PATH environment variable so that the commands can be run from any directory. The bin directory can be found directly inside your Ruby installation directory, such as C:\ruby\bin.

  1. Use the RubyGems packaging system to install SOAP4R by issuing the following command: gem install soap4r --source
  2. Edit the classDefCreator.rb file under C:\ruby\lib\ruby\1.8\wsdl\soap to direct soap4r to support anonymous types. Search for the text do we define a class for local complexType from it's name? in the file, and comment out the text type = nil just above it. Uncomment the text type = create_class_name(
    Figure 14. classDefCreator.rb

Generate the Web service client code

Running on a remote server

In this article, you run the Web service and the client on the same computer. If you plan to invoke your service from a remote computer, you need to edit the Export1_TestServiceInterfaceHttp_Service.wsdl file with the correct server name for your Web service. The default name is localhost. Correct the server name before running the wsdl2ruby.rb script.

  1. Create a folder to hold the Web service client code. In this article, use C:\GeneratedRubyScripts.
  2. Select the Data Types, Interface, and Web Service Port in WebSphere Integration Developer, and copy them into C:\GeneratedRubyScripts.
    Figure 15. Copying files into C:\GeneratedRubyScripts
    Copying files into C:\GeneratedRubyScripts

    The following files should now be in C:\GeneratedRubyScripts:

    • TestServiceData.xsd
    • TestServiceInterface.wsdl
    • Export1_TestServiceInterfaceHttp_Service.wsdl

    As of version 1.5.6 of SOAP4R, the generation of Web service clients from multiple wsdl files is not supported. Therefore, combine the two wsdl files.

  3. Open the Export1_TestServiceInterfaceHttp_Service.wsdl file in a text editor, and copy the binding and service elements as shown in Figure 16.
    Figure 16. Copying the binding and service elements only
    Copying the binding and service elements only
  4. Paste this text to the bottom of the TestServiceInterface.wsdl file.
  5. Copy and paste the SOAP namespace xmlns:soap=" from Export1_TestServiceInterfaceHttp_Service.wsdl to TestServiceInterface.wsdl. Be sure to paste it inside of the definitions element, as shown in Figure 17.
  6. In the binding element of the TestServiceInterface.wsdl file, change type="Port_0:TestServiceInterface to type="tns:TestServiceInterface.
  7. In the service element of the TestServiceInterface.wsdl file, change binding="this:Export1_TestServiceInterfaceHttpBinding" to binding="tns:Export1_TestServiceInterfaceHttpBinding".
    Figure 17. Configured TestServiceInterface.wsdl
    Configured TestServiceInterface.wsdl
  8. Navigate to the GeneratedRubyScripts directory, correct the server name if needed (see Running on a remote server sidebar), and run the following command to generate the Web service client files: wsdl2ruby.rb --wsdl TestServiceInterface.wsdl --type client --classdef --force.
  9. Ensure that the command returns End of app. (status: 0), as shown in Figure 18.
    Figure 18. wsdl2ruby.rb output
    wsdl2ruby.rb output

    After running the script, the following files should be generated:

    • TestServiceInterface.rb
    • TestServiceInterfaceDriver.rb
    • TestServiceInterfaceMappingRegistry.rb
    • Export1_TestServiceInterfaceHttpServiceClient.rb
  10. Open the TestWebServiceMappingRegistry.rb file, and ensure that the following lines of code are present at the top of the file in the correct order. You might have to add the reference to rubygems and soap4r.
    Listing 3. Code for configuring module dependencies
    require 'TestServiceInterface.rb'
    require 'rubygems'
    gem 'soap4r'
    require 'soap/mapping'
  11. Open the Export1_TestServiceInterfaceHttpServiceClient.rb file, and replace the last two lines with the following code to call the service. In this test, you will send Ruby on Rails as the service input.
    Listing 4. Code for setting up the call to the service
    # Setup call to the Web Service      
    testServiceInput        ="Ruby", "on", "Rails")
    callTestServiceInput    =
    # Call Web Service
    callTestServiceResponse = obj.callTestService(callTestServiceInput)
    # Print Response
    puts callTestServiceResponse.output.returnMessage

Test the Web service using the Ruby standalone script

Ensure that the WebSphere Process Server is running, and run the following command from the command prompt: ruby -d Export1_TestServiceInterfaceHttpServiceClient.rb. Note: The -d option is used to display the SOAP wire dumps during service execution, if needed.

Figure 19. Output of service call without the SOAP wire dump
Output of service call without the SOAP wire dump

Using the generated client files in a Rails application

Create a new Rails application

About WEBrick

WEBrick is a pure-Ruby Web server that is distributed with Ruby 1.8.1 and later. Ruby on Rails uses it to test applications in a development environment. WEBrick provides simple HTTP Web server services, but code for simple server services other than HTTP is also available. Mongrel or Lighttpd are two other HTTP Web servers frequently used with Ruby.

  1. Run the rails webServiceDemo command to create a new Rails application and folder structure under the GeneratedRubyScripts directory. After running the command, you should have a webServiceDemo directory created to hold the artifacts for the Web application.
  2. Modify the boot.rb file under webServiceDemo\config to ensure that SOAP4R loads properly. Search for require 'rubygems' in the file, and add gem 'soap4r' below it.
    Figure 20. Modify boot.rb.
    Modify boot.rb.
  3. Change directory to webServiceDemo, and create a new controller called WebService using the following command: ruby script/generate controller WebService.
    Figure 21. Creating the Rails controller
    Creating the Rails controller
  4. Edit the web_service_controller.rb file located in webServiceDemo\app\controllers. Add require 'TestServiceInterfaceDriver.rb' to the top of the web_service_controller.rb file so that the driver can be loaded.
  5. Add code from Listing 5 to create the action. Notice that the code is similar to the code that was used in the Export1_TestServiceInterfaceHttpServiceClient.rb standalone Ruby script in Listing 4.
    Listing 5. Code for creating the action
    require 'TestServiceInterfaceDriver.rb'
    class WebServiceController < ApplicationController
      def invoke
      # Setup call to the Web Service      
      testServiceInput        ="Ruby", "on", "Rails")
      callTestServiceInput    =
      # Call Web Service
      obj =
      callTestServiceResponse = obj.callTestService(callTestServiceInput)
      # Assign Response Message
      @returnMessage = callTestServiceResponse.output.returnMessage
  6. Copy the Web service client files from the GeneratedRubyScripts directory to the webServiceDemo\lib directory so they can be used by the controller. The following files are needed:
    • TestServiceInterface.rb
    • TestServiceInterfaceDriver.rb
    • TestServiceInterfaceMappingRegistry.rb
  7. In order to create a view for the invoke action, create a file called invoke.rhtml in the webServiceDemo\app\views\web_service directory, and copy the following code into the file:
    Listing 6. Code for creating the action
    		<title>Invoke Web Service</title>
    		<h1><%= @returnMessage %></h1>

    Notice that the @returnMessage instance variable that is used in the code above was set in the action code from Listing 5.

  8. Start the WEBrick Web server (see the sidebar About WEBrick) by running the following command: ruby script/server webrick.
  9. Access the page using the following URL: http://localhost:3000/web_service/invoke.
    Figure 22. View of Web page
    View of Web page


This article used a simple SCA service to demonstrate how to integrate a Ruby on Rails Web application with a WebSphere Process Server module. The article offered the steps on how to expose an SCA module as a Web service in WebSphere Integration Developer and how to use SOAP4R to generate Ruby scripts that can be migrated into a Ruby on Rails Web application. The scope of the article was limited to the integration of WebSphere Process Server and Ruby on Rails; therefore, there are many features of Ruby on Rails and WebSphere Process Server that were not highlighted (see Resources for further exploration of these topics).


Sample test fileTestServiceData.xsd695 KB



Get products and technologies

  • Innovate your next development project with IBM trial software, available for download or on DVD.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks

Zone=SOA and web services, WebSphere
ArticleTitle=Create a Web service with Ruby on Rails for integration with WebSphere Process Server