Web services

A participant can request a Web service provided by the Community Manager. Similarly, the Community Manager can request a Web service provided by a participant. The participant or Community Manager invokes the WebSphere Partner Gateway server to obtain the Web service. WebSphere Partner Gateway acts as a proxy, passing the Web service request to the Web service provider and returning the response synchronously from the provider to the requester.

This section contains the following information for setting up a Web service for use by a participant or a Community Manager:

Identifying the participants for a Web service

When a Web service is provided by the Community Manager for use by participants, WebSphere Partner Gateway requires that a participant identify itself. When posting the Web service request, set the identity in one of the following two ways:

  1. Use HTTP Basic Authentication with User ID of the form <participant's_business_ID>/<console_user_name> (for example, 123456789/joesmith) and a password equal to the console user name's password.
  2. Present an SSL client certificate that has been previously loaded into WebSphere Partner Gateway for the participant

When the Web service is provided by a participant, for use by the Community Manager, the public URL used by the Community Manager to invoke the Web service should contain the query string ?to=<participant's_business_ID>. An example is:

http://<IP_address>/bcgreceiver/Receiver?to=123456789

This tells WebSphere Partner Gateway that the provider of the Web service is the participant with business ID 123456789.

Creating document flow definitions

To set up the document flow definition, you either upload the WSDL (Web Service Definition Language) files that define the Web service, or you enter the equivalent document flow definitions manually through the Community Console.

Uploading the WSDL files for a Web service

The definition for a Web service should be contained in a primary WSDL file, with extension .wsdl, which might import additional WSDL files through the import element. If there are imported files, these can be uploaded with the primary file using one of the following methods:

For example, suppose the primary WSDL file helloworldRPC.wsdl contains the following import element:

<import namespace="http://www.helloworld.com/wsdl/helloRPC.wsdl" location=
"bindingRPC.wsdl"/>

And suppose the imported WSDL file bindingRPC.wsdl contains the following import element:

<import namespace="http://www.helloworld.com/wsdl/helloRPC.wsdl" location=
"port/porttypeRPC.wsdl"/>

The file should contain the following:

Name                   Path

helloworldRPC.wsdl

bindingRPC.wsdl

porttypeRPC.wsdl               port\

When a WSDL file definition of a Web service is uploaded, the original WSDL is saved as a validation map. (Web service messages are not actually validated by WebSphere Partner Gateway. They are passed through directly, with the original service end-point URL.) This is called the private WSDL.

In addition, a public WSDL is saved with the private URL replaced by the target URL specified on the Upload/Download Packages page. The public WSDL will be provided to the users of the Web service, who will invoke the Web service at the target's URL (the public URL). WebSphere Partner Gateway will then route the Web service request to a gateway that is the original Web service provider's private URL. WebSphere Partner Gateway acts as a proxy, forwarding the Web service request to a private provider URL, which is hidden from the Web service user.

Both the private and public WSDLs (including any imported files) can be downloaded from the Community Console after the WSDL has been uploaded.

Uploading WSDL files using the Community Console

WebSphere Partner Gateway provides a way to import WSDL files. If a Web service is defined in a single WSDL file, you can upload the WSDL file directly. If the Web service is defined using multiple WSDL files (this happens when you have imported WSDL files within a primary WSDL file), they would be uploaded in a zipped archive.

Important: The WSDL files within the zipped archive must be within a directory specified in the WSDL import element. For example, suppose you have the following import element:
<import namespace="http://www.helloworld.com/wsdl/helloRPC.wsdl" 
location="path1/bindingRPC.wsdl"/>
The directory structure within the zipped archive would be: path1/bindingRPC.wsdl.

Now consider this example:

<import namespace="http://www.helloworld.com/wsdl/helloRPC.wsdl"
 location="bindingRPC.wsdl"/>.

The bindingRPC.wsdl file would be at the root level within the zipped archive.

To upload a single WSDL file or zipped archive, use the following procedure.

  1. Click Hub Admin > Hub Configuration > Document Flow Definition.
  2. Click Upload/Download Packages.
  3. For WSDL Package, click Yes.
  4. For Web Service Public URL, perform one of the following steps:
  5. Click Browse and select the WSDL file or zipped archive.
  6. For Commit to Database, select No if you want to upload the file in test mode. When you select No, the file will not be installed into the system. Use the system-generated messages displayed in the Messages box to troubleshoot upload errors. Select Yes to upload the file into the system database.
  7. For Overwrite Data, select Yes to replace a file currently in the database. Select No to add the file to the database.
  8. Click Upload. The WSDL file is installed into the system.
Validating packages using schema files

A set of XML schemas that describe the XML files that can be uploaded through the console is provided on the WebSphere Partner Gateway installation medium. Uploaded files are validated against these schemas. The schema files are a useful reference for determining the cause of an error when a file cannot be uploaded because of non-conforming XML. The files are: wsdl.xsd, wsdlhttp.xsd, and wsdlsoap.xsd, which contain the schema describing valid Web Service Definition Language (WSDL) files.

The files are located in: B2BIntegrate\packagingSchemas

Creating the document flow definition manually

To enter the equivalent document flow definitions manually, follow the procedures in this section. You must also create the Document Flow, Activity, and Action entries individually under Protocol: Web Service, paying particular attention to the requirements for the Action and its relationship to the received SOAP messages.

In terms of the Package/Protocol/Document Flow/Activity/Action hierarchy of document flow definitions, a supported Web service is represented as:

The critical definitions are the Actions because WebSphere Partner Gateway will use an Action's namespace and name to recognize an incoming Web service request SOAP message and route it appropriately based on a defined participant connection. The namespace and name of the first child XML element of the received SOAP message's soap:body element must match a known Action's namespace and name in WebSphere Partner Gateway's document flow definitions.

For example, suppose a Web service request SOAP message for a document-literal SOAP binding is:

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/
2001/XMLSchema-instance">
 <soapenv:Body>
  <nameAndAddressElt xmlns="http://www.helloworld.com/xsd/helloDocLitSchema">
   <titleElt xmlns="">Mr</titleElt>
   <nameElt xmlns="">Joe Smith</nameElt>
   <addressElt xmlns="">
    <numberElt>123</numberElt>
    <streetElt>Elm St</streetElt>
    <cityElt>Peoria</cityElt>
   </addressElt>
  </nameAndAddressElt>
 </soapenv:Body>
</soapenv:Envelope>

WebSphere Partner Gateway would look for a defined Web Service Action with this code:

{http://www.helloworld.com/xsd/helloDocLitSchema}:nameAndAddressElt

For an RPC binding style SOAP request message, for example:

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/
2001/XMLSchema-instance">
 <soapenv:Body>
  <ns1:helloWorldRPC soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/ xmlns:ns1="http://www.helloworld.com/helloRPC">
   <name xsi:type="xsd:string">Joe Smith</name>
  </ns1:helloWorldRPC>
 </soapenv:Body>
</soapenv:Envelope>

WebSphere Partner Gateway would look for a defined Web Service action with this code:

{http://www.helloworld.com/helloRPC}:helloWorldRPC

For an RPC binding, the namespace and name of the first child element of the soap:body of a SOAP request message should be the namespace and name of the applicable Web service operation.

For Document-Literal binding, the namespace and name of the first child element of the soap:body of a SOAP request message should be the namespace and name of the XML element attribute in the part element of the input message definition for the Web service.

Creating interactions

To create an interaction for a Web service, you use the same Web service document flow action for both the Source and the Target.

To create interactions, use the following procedure.

  1. Click Hub Admin > Hub Configuration > Document Flow Definition.
  2. Click Manage Interactions.
  3. Click Create Interaction.
  4. Under Source, expand Package: None > Protocol: Web Service > Document Flow: < document flow> > Action: <action>. Repeat this step in the Target column.
  5. Select Pass Through from the Action list at the bottom of the page. (Pass Through is the only valid option supported in WebSphere Partner Gateway for a Web service.)

Restrictions and limitations of Web service support

WebSphere Partner Gateway supports the following standards:

Note:

Copyright IBM Corp. 2003, 2005