Broker implements new Web service - detail

This is an overview of a typical end-to-end scenario where the broker implements a Web service.

An existing C or COBOL based system offers some business logic which can usefully be exposed as a Web service.

There is some mechanism for the broker to invoke operations on the existing system (that is, the system exposes an interface to the broker). Typically the existing system would be enabled for WebSphere MQ, meaning that it receives MQ messages containing application data, dispatches these to the underlying implementation and then packages the return values as an MQ response. The data structures supplied to and returned by these existing operations are defined in a C header file or COBOL copybook.

The Web service is to offer an interface based on the operations already exposed by the existing system. This interface might comprise all the existing operations, some subset of them and/or composite operations.

To define your interface:
  1. Look at the business function offered by the existing system
  2. Select the subset of this business function to be exposed
  3. Decide how that is to be represented in the interface (as many discrete operations, or as fewer multipurpose operations)
A basic decision is whether the Web service interface will be RPC-style or document-style. (See Web services, WSDL and message flows and Relationship of WSDL to Message Model).
  • An RPC-style interface is generally designed to map on to an underlying set of operations provided by some API, and the individual operations (method calls) have relatively small payloads.
  • A document-style interface might have fewer operations each with a larger payload – for instance this might be a document representing a loan request.
The WS-I (see http://www.ws-i.org/) recommend the use only of document-style WSDL, but many older Web services use RPC-style.

To implement the scenario:

  1. Import the existing API data structures – for example using the C importer. If document-style WSDL is to be used, you must have the importer wizard create the required global elements in the broker model. The WS-I recommends that the Web service payload be namespace qualified, so the user should specify the target namespace on the import.

    At this stage you have a message model for the data to be used in invoking the existing operations.

  2. Generate the WSDL definition. Unless you have already created the required Message Categories, create a Message Category for each Web services operation to be exposed and associate the existing broker messages with the appropriate SOAP roles (input, output or fault). (See Working with a message category file)
    • If you chose document-style WSDL, the message set itself is not modified.
    • If you chose RPC-style WSDL, messages corresponding to the request and response for each WSDL operation are created and added to the message set automatically
  3. The WSDL generation step will result in the appropriate SOAP mxsds (message definition files) being automatically included in the message set. Specifically this includes the SOAP envelope mxsd and (if the WSDL style is RPC-encoded) the SOAP encoding mxsd.
  4. If you are creating a new Web services client, use the generated WSDL with your chosen Web services client technology. You do this with a tool other than WebSphere Message Broker, for example Rational Application Developer or .NET.
  5. Implement a message flow to receive the Web service request, that is, to act as the Web services provider. The endpoint nodes are HTTP or MQ depending on the transport used by the client. The input node properties are:
    • domain: "MRM"
    • set: the message set containing the SOAP Envelope definition
    • type: "Envelope"
    • format "XML1"
  6. When invoked by the flow, the parser creates a logical tree comprising the SOAP envelope as defined by the pre-canned SOAP mxsd. Parsing continues automatically at the attachment points within the SOAP envelope (SOAP body and header), attempting to match against other message definitions in the message set. Apply validation at the input node if required.

    At this stage you have a logical tree, but you do not know which SOAP payload has been received. You could check the HTTP SOAPAction/action field to determine the likely content but this only works for HTTP. (Use of SOAPAction is not recommended by the WS-I.)

  7. You can provide mapping from the allowed payload messages to the required messages from the existing system. For example you can have a single mapping definition with messages message1a and message1b both mapped to the same target message2.
    Alternatively, separate mappings could be provided for each message type – or for groups of related message types. This approach might result in more manageable and reusable mapping definitions. The disadvantage is that the user has to determine which payload they have received before they can apply the mapping. This can be done in ESQL as follows:
     
     DECLARE SOAPENV NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
     SET contentType = FIELDNAME(InputBody.SOAPENV:Body.*[<]);
     IF (contentType = ‘foo’) ...
     
    or using a field reference, for example:
     
     DECLARE R REFERENCE TO InputRoot.MRM.SOAPENV:Body.*[<];
     IF (FIELDNAME(R) = “foo”) ...
     
    Following that, now that the content is known, the flow could branch appropriately (for example using a RouteToLabel node) with each branch having content-specific Mapping and/or Compute nodes. For simple flows all the logic could be kept in a single Compute node if required.

    Now invoke the existing system (typically over WebSphere MQ), retrieve any expected response, and propagate the Web service reply. The dataflow designer must account for the possibility that the business application does not send the expected response in a reasonable period of time.

For a similar scenario, see the sample: Web Service Host sample.

Related concepts
Web services, WSDL and message flows
Broker calls existing Web service
Broker implements new Web service interface
Broker implements existing Web service interface
Broker implements non-web-service interface to new Web service
Related tasks
Broker implements existing Web service interface - detail
Broker calls existing Web service - detail