Building the Web Service sample

The Web Service sample has two parts:

Building the Web Service Host sample

All the files that you need to run the Web Service Host sample are supplied, but if you prefer to create the sample yourself, follow the instructions below:

To build the Web Service Host sample:

  1. Import the Web Service sample from the Samples Gallery so that the C header file is available for you to use. Create a message set to serve both the Web service format message (XML) and the legacy format (CWF):
    1. Start the Message Brokers Toolkit.
    2. Switch to the Broker Application Development perspective.
    3. Click File > New > Message Set.
    4. Set Message set name to WSHOST_MS1.
    5. Set Message set project name to WSHOST_BUILD_MSP1, then click Next.
    6. Click XML documents and Binary data, then click Finish.
    7. Save and close messageSet.mset.
  2. Import a C header file, which maps to the input and output message of the legacy application:
    1. Click File > Import > File system, then click Next.
    2. Browse to find project WSHOST_LEGACY1, then click Select All.
    3. Set Into folder to WSHOST_BUILD_MSP1, then click Finish.
    4. Create a message definition file from the C header file:
      1. In the Broker Development view, right-click legacyservice.h, then click New > Message Definition File From > C Header File.
      2. Set Message set to /WSHOST_BUILD_MSP1/WSHOST_MS1.
      3. Set Target namespace to http://www.brokersamplewshost.ibm.com, then click Next.
      4. In the Source structures pane, click tagIA81CONF, click the > button, then click Select all > Finish.
    5. Save and close legacyservice.mxsd.
  3. Build a SOAP message definition:
    1. In the Broker Development view, right-click message set WSHOST_MS1, then click New > Message Definition File From > IBM Supplied Message.
    2. In the IBM supplied messages pane, select message ibm\soap\envelope\soapenv11.xsd, then click Next.
    3. Expand WSHOST_BUILD_MSP1, select WSHOST_MS1, then click Finish.
    4. Save and close soapenv11.mxsd.
    5. Notice that Envelope is automatically created as a message.

      Several warnings are shown in the Problems view of the Message Brokers Toolkit. These are mainly caused by having a CWF defined for a SOAP message definition. You can ignore the warnings.

  4. Create a category for the messages (a prerequisite of generating WSDL).

    In WSDL, all operation names must be unique within an enclosing port type. So the request and response messages that are defined in a message category must be different. In order to clarify this, two new messages will be defined to the message set, one for Web services input, one for Web services output. These are to be created in the mxsd file that is populated from the C header file.

    To create a category:

    1. In the Broker Development view, double-click legacyservice.mxsd.
    2. In the Outline view, right-click Elements and Attributes, then click Add Global Element.
    3. Change the name of the new element to IA81CONFIN, then press Enter.
    4. In the Type cell for the IA81CONFIN element, click (More...) from the list.
    5. Click tagIA81CONF, then click OK.
    6. In the Outline view, right-click Messages, then click Add Message From Global Element.
    7. Click tns:IA81CONFIN from the list, then press Enter.
    8. In the Outline view, right-click Elements and Attributes, then click Add Global Element.
    9. Change the name of the element to IA81CONFOUT, then press Enter.
    10. In the Type cell for the IA81CONFOUT element, click (More...) from the list.
    11. Click tagIA81CONF and click OK.
    12. In the Outline view, right-click Messages and click Add Message From Global Element.
    13. Click tns:IA81CONFOUT from the list and press Enter.
    14. Save and close legacyservice.mxsd.
    15. Click File > New > Message Category File.
    16. Set Category Kind to wsdl.
    17. Set Category Usage to wsdl:requestresponse, then click Next.
    18. Select message set WSHOST_MS1 within message set project WSHOST_MSP1.
    19. In the File name field, type cat1 then click Next.
    20. In the top pane, select IA81CONFIN and IA81CONFOUT (press and hold ctrl to make multiple selections).
    21. In the bottom pane, set the value in the Kind cell for IA81CONFOUT to output (click the cell to display a menu from which you can select the value).
    22. In the bottom pane, select IA81CONFIN, then click Finish.
    The new message category file is created.
  5. Generate WSDL:
    1. Click File > New > WSDL Definition > Next.
    2. Click message set WSHOST_MS1 within message set project WSHOST_MSP1, then click Next.
    3. Click WSHOST_MSP1, then click Create New Folder.
    4. Type wsdl as the folder name, then click OK.
    5. Ensure that Single is selected, then click Next.
    6. In the "Specify WSDL details" pane, ensure that Style is set to document, then click Next.
    7. In the "Select categories" pane, click Select All > Next.
    8. In the Bindings pane, click SOAP/HTTP > Next.
    9. In the "Service properties" pane, set Port Address to http://localhost:7080/samplebrokerwshost then click Finish.
  6. Create a message flow. The flow takes a HTTP request, runs the legacy application using MQ, and routes information from the legacy application's response to the HTTP requestor.

    To create the message flow:

    1. Click File > New > Message Flow Project.
    2. Set Project name to WSHOST_BUILD_MFP1, then click Next.
    3. In the "Referenced projects" pane, select WSHOST_BUILD_MSP1 then click Finish.
    4. In the Broker Development view, right-click WSHOST_BUILD_MFP1, then click New > Message Flow.
    5. Set Message flow name to WSHOST_WSHOST1.
    6. Set Schema to WSHOST_MFP1, then click Finish.
    7. In the Message Flow editor, add and rename the nodes listed in the following table.
      For instructions, see Adding a node.
      Palette drawers Node type Node name
      HTTP HTTPInput HTTP Input
      Transformation Compute Compute
      Transformation Compute Compute1
      Transformation Compute Compute2
      WebSphere MQ MQOutput MQOutput to legacy
      WebSphere MQ MQOutput MQOutput store HTTP state
      WebSphere MQ MQGet MQGet stored HTTP state
      WebSphere MQ MQInput MQInput from legacy
      HTTP HTTPReply HTTPReply
    8. Connect the nodes together as shown in the following table.
      For instructions, see Connecting nodes.
      Node name Terminal Connect to this node
      HTTPInput Out Compute
      Compute Out MQOutput to legacy
      MQOutput to legacy Out Compute1
      Compute1 Out MQOutput store HTTP state
      MQInput from legacy Out MQGet stored HTTP state
      MQGet stored HTTP state Out Compute2
      Compute2 Out HTTPReply
  7. Customize the HTTP Input node:
    1. Right-click the HTTP Input node, and click Properties.
    2. Click Basic, and set Path suffix for URL to /samplebrokerwshost.
    3. Click Input Message Parsing:
      • For Message domain, select MRM from the list.
      • For Message set, select WSHOST_MS1 from the list.
      • For Message type, type Envelope.
      • For Message format, select XML1 from the list.
    4. Save and close the Properties dialog.
  8. Customize the Compute node:
    1. Right-click the Compute node, and click Open ESQL.
    2. Type the following ESQL between the BEGIN and END statements for this module. Use Content Assist (Ctrl + space) to select keywords. DECLARE NAMESPACE statements similar to the statements that are commented on the first two lines are generated when you use Content Assist for the first time to select the SOAP Body element and any IA81CONFIN elements. If you are copying and pasting this code, ensure that you uncomment the DECLARE NAMESPACE statements.
      --DECLARE tns NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
      --DECLARE ns NAMESPACE 'http://www.brokersamplewshost.ibm.com';
      
      	CALL CopyMessageHeaders();
      
      -- Output is MQ, so remove HTTP headers
      	SET OutputRoot.HTTPInputHeader = null;
      
      -- Output is legacy, so set wire format and message name
      	SET OutputRoot.Properties.MessageType = 'msg_tagIA81CONF';
      	SET OutputRoot.Properties.MessageFormat = 'CWF1';
      
      -- Add an MQMD
      	CREATE NEXTSIBLING OF OutputRoot.Properties DOMAIN 'MQMD';
      
      -- Build message to be sent to legacy
      	SET OutputRoot.MRM.MessageId
      	    = InputBody.tns:Body.ns:IA81CONFIN.MessageId;
      	SET OutputRoot.MRM.OrderNumber
          	= InputBody.tns:Body.ns:IA81CONFIN.OrderNumber;
      	SET OutputRoot.MRM.ItemReference
          	= InputBody.tns:Body.ns:IA81CONFIN.ItemReference;
      	SET OutputRoot.MRM.ItemQuantity
          	= InputBody.tns:Body.ns:IA81CONFIN.ItemQuantity;
      	SET OutputRoot.MRM.CustomerNumber
          	= InputBody.tns:Body.ns:IA81CONFIN.CustomerNumber;
      	SET OutputRoot.MRM.DeliveryRef 
          	= InputBody.tns:Body.ns:IA81CONFIN.DeliveryRef;
      	SET OutputRoot.MRM.Confirm 
          	= InputBody.tns:Body.ns:IA81CONFIN.Confirm;
      	SET OutputRoot.MRM.filler1 
          	= InputBody.tns:Body.ns:IA81CONFIN.filler1;
      
      	RETURN TRUE;
  9. Customize the MQOutput to legacy node:
    1. Right-click the MQOutput to legacy node, and click Properties.
    2. If you intend to run the legacy application on a different WebSphere MQ queue manager to the broker, select Basic, and set Queue manager name to the name of your legacy application's queue manager. Otherwise, leave it blank.
    3. Set Queue name to WSHOST1_OUT1.
    4. Click Advanced and set Transaction mode to Yes.
    5. Set Message context to Default.
    6. Click Request, and select Request.
    7. Set Reply-to queue to WSHOST1_IN1, then save and close the Properties dialog.
  10. Customize the Compute1 node:
    1. Right-click the Compute1 node, and click Open ESQL.
    2. Code the following ESQL between the BEGIN and END statements for this module. Use Content Assist (Ctrl + space) to select keywords. A DECLARE NAMESPACE statement similar to the statement that is commented on the first line is generated when Content Assist is used for the first time to select the SOAP Body element.
      --DECLARE tns NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
      --DECLARE ns NAMESPACE 'http://www.brokersamplewshost.ibm.com';
      
      -- The output message built in this node stores the HTTP context.
      -- Any format may be suitable, but we are using a
      -- self-defined field in a SOAP Header to do this
      -- So the wire format is XML
      -- Create the target message set properties
      
      	SET OutputRoot.Properties.MessageSet = InputRoot.Properties.MessageSet;
      	SET OutputRoot.Properties.MessageType = 'Envelope';
      	SET OutputRoot.Properties.MessageFormat = 'XML1';
      
      -- Create the MQMD and set the CorrelId
      -- The CorrelId needs to be set to the MsgId of the message sent
      -- to the legacy application.  When the reply from the legacy
      -- application is received, we will MQGet from the store
      -- queue with correlid equal to the correlid of the legacy reply
      
      	SET OutputRoot.MQMD.CorrelId
      = InputLocalEnvironment.WrittenDestination.MQ.DestinationData.msgId;
      
      -- Build message to store HTTP context
      
      	SET OutputRoot.MRM.tns:Header.HTTP.RequestIdentifier
          = InputLocalEnvironment.Destination.HTTP.RequestIdentifier;
      
      	RETURN TRUE;
  11. Customize the MQOutput store HTTP state node:
    1. Right-click the MQOutput store HTTP state node, and click Properties.
    2. Click Basic, and set Queue manager name to WSHOST1_STATE1.
    3. Click Advanced and set Transaction mode to Yes.
    4. Set Message context to Default.
    5. Save and close the Properties dialog.
  12. Customize the MQInput from legacy node:
    1. Right-click the MQInput from legacy node, and click Properties.
    2. Click Basic, and set Queue name to WSHOST1_IN1.
    3. Click Input Message Parsing:
      • For Message domain, select MRM from the list.
      • For Message set, select WSHOST_MS1 from the list.
      • For Message type, enter msg_tagIA81CONF.
      • For Message format, select CWF1 from the list.
    4. Save and close the Properties dialog.
  13. Customize the MQGet stored HTTP state node:
    1. Right-click the MQGet stored HTTP node, and click Properties.
    2. Click Basic, and set Queue name to WSHOST1_STATE1.
    3. Click Input Message Parsing:
      • For Message domain, select MRM from the list.
      • For Message set, select WSHOST_MS1 from the list.
      • For Message type, enter Envelope.
      • For Message format, select XML1 from the list.
    4. Click Advanced:
      • For Generate mode, select Message and LocalEnvironment from the list.
      • For Copy message, select Copy Entire Message from the list.
    5. Click Request, and select the check box for Get by correlation ID.
    6. Click Result, and set Output data location to OutputLocalEnvironment.
    7. Save and close the Properties dialog.
  14. Customize the Compute2 node:
    1. Right-click the Compute2 node, and click Properties.
    2. Click Basic, and set Compute mode to LocalEnvironment and Message.
    3. Save and close the Properties dialog.
    4. Right-click the node, and click Open ESQL.
    5. Type the following ESQL between the BEGIN and END statements for this module:
      --DECLARE tns NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
      --DECLARE ns NAMESPACE 'http://www.brokersamplewshost.ibm.com';
      
      -- Input is CWF, output is SOAP/XML
      	SET OutputRoot.Properties.MessageSet = InputRoot.Properties.MessageSet;
      	SET OutputRoot.Properties.MessageType = 'Envelope';
      	SET OutputRoot.Properties.MessageFormat = 'XML1';
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFOUT = InputRoot.MRM;
      
      -- Set the http reply identifier
      	SET OutputLocalEnvironment.Destination.HTTP.RequestIdentifier =
       CAST(InputLocalEnvironment.MRM.tns:Header.HTTP.RequestIdentifier AS BLOB);
      	
      	RETURN TRUE;
  15. Save and close WSHOST_WSHOST1.esql.
  16. Save and close WSHOST_WSHOST1.msgflow.
  17. If you intend to run the legacy application on a different WebSphere MQ queue manager to the broker, define the legacy application's input queue to the legacy application's queue manager. Use the appropriate WebSphere MQ utility to enter the following queue definition:

    DEFINE QLOCAL(WSHOST1_OUT1) REPLACE

Building the Web Service Client sample

All the files that you need to run the Web Service Client sample are supplied, but if you prefer to create the sample yourself, follow the instructions below:

To build the Web Service Client sample:

  1. Import the Web Services sample from the Samples Gallery so that the C header file is available for you to use. Create a message set to serve both the Web service format message (XML) and the legacy format (CWF).
    1. Start the Message Brokers Toolkit.
    2. Switch to the Broker Application Development perspective.
    3. Click File > New > Message Set.
    4. Set Message set name to WSCLIENT_MS1.
    5. Set Message set project name to WSCLIENT_BUILD_MSP1, then click Next.
    6. Click XML documents and Binary data, then click Finish.
    7. Save and close messageSet.mset.
  2. Import a C header file which maps the input and output message of the legacy application:
    1. Copy file legacyservice.h from project WSHOST_LEGACY1, and paste it into project WSCLIENT_BUILD_MSP1.
    2. Create a message definition file from the C header file:
      1. In the Broker Development view, right-click legacyservice.h, then click New > Message Definition File From > C Header File.
      2. Set Message set to /WSCLIENT_BUILD_MSP1/WSCLIENT_MS1, then click Next.
      3. In the Source structures pane, click tagIA81BUY, click the > button, click tagIA81CONF, click the > button, then click Select all > Finish.
    3. Save and close legacyservice.mxsd.
  3. Import the WSDL for the web service.
    1. Click File > Import > File System > Next.
    2. Browse to select directory wsdl from project WSHOST_MSP1.
    3. Set Into folder to WSCLIENT_MSP1, then click Finish
    4. Create a message definition file from the WSDL:
      1. In the Broker Development view, right-click WSHOST_MS1Service.wsdl, within the wsdl directory of project WSCLIENT_MSP1 then click New > Message Definition File.
      2. The radio button for WSDL file should be preselected. If not, select it then click Next.
      3. Within project WSCLIENT_MSP1, WSHOST_MS1Service.wsdl should be preselected. If not, select it then click Next.
      4. In the Message sets pane, expand WSCLIENT_MSP1 and click WSCLIENT_MS1.
      5. In the namespace pane, set the namespace prefix for namespace http:www.brokersamplewshost.ibm.com to wshost then click Next.
      6. You are shown a list of files which will be generated. Click Finish.
  4. Create a message flow. The flow takes a HTTP request, runs the legacy application using MQ, and routes information from the legacy application's response to the HTTP requestor.

    To create the message flow:

    1. Click File > New > Message Flow Project.
    2. Set Project name to WSCLIENT_BUILD_MFP1, then click Next.
    3. In the "Referenced projects" pane, select WSCLIENT_BUILD_MSP1, then click Finish.
    4. In the Broker Development view, right-click WSCLIENT_BUILD_MFP1, then click New > Message Flow.
    5. Set Message flow name to WSCLIENT_WSCLIENT1.
    6. Set Schema to WSCLIENT_MFP1, then click Finish.
    7. In the Message Flow editor, add and rename the nodes listed in the following table.
      For instructions, see Adding a node.
      Palette drawers Node type Node name
      WebSphere MQ MQInput MQInput from legacy
      Transformation Compute Compute
      Transformation Compute Compute1
      WebSphere MQ MQReply MQReply
      HTTP HTTPRequest HTTPRequest
    8. Connect the nodes together as shown in the following table.
      For instructions, see Connecting nodes.
      Node name Terminal Connect to this node
      MQInput from legacy Out Compute
      Compute Out HTTPRequest
      HTTPRequest Out Compute1
      Compute1 Out MQReply
  5. Customize the MQInput from legacy node:
    1. Right-click the MQInput from legacy node, and click Properties.
    2. Click Basic, and set Queue name to WSCLIENT1_IN1.
    3. Click Input Message Parsing :
      • For Message domain, select MRM from the list.
      • For Message set, select WSCLIENT_MS1 from the list.
      • For Message type, select msg_tagIA81BUY from the list.
      • For Message format, select CWF1 from the list.
    4. Save and close the Properties dialog.
  6. Customize the Compute node:
    1. Right-click the Compute node, and click Open ESQL.
    2. Type the following ESQL between the BEGIN and END statements for this module. Use Content Assist (Ctrl + space) to select keywords. DECLARE NAMESPACE statements similar to the statements that are commented on the first two lines are generated when you use Content Assist for the first time to select the SOAP Body element and any IA81CONFIN elements. If you are copying and pasting this code, ensure that you uncomment the DECLARE NAMESPACE statements.
      --DECLARE tns NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
      --DECLARE ns NAMESPACE 'http://www.brokersamplewshost.ibm.com';
      
          CALL CopyMessageHeaders();
      
      -- Save the MQMD; sending to HTTP later in the flow destroys it
      	SET Environment.MQMD = InputRoot.MQMD;
          
      -- Input is CWF, Output is SOAP, so set wire format and message name
      	SET OutputRoot.Properties.MessageType = 'Envelope';
      	SET OutputRoot.Properties.MessageFormat = 'XML1';
      
      -- Build message to be sent to web service
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.MessageId = 'IA81CONF';
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.OrderNumber = InputBody.OrderNumber;
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.ItemReference = InputBody.ItemReference;
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.ItemQuantity = InputBody.ItemQuantity;
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.CustomerNumber = InputBody.CustomerNumber;
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.DeliveryRef = ' ';
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.Confirm = ' ';
      	SET OutputRoot.MRM.tns:Body.ns:IA81CONFIN.filler1 = ' ';
      
      	RETURN TRUE;
  7. Customize the HTTPRequest node:
    1. Right-click the HTTPRequest node, and click the Properties dialog.
    2. Select Basic, and set Web service URL to http://localhost:7080/samplebrokerwshost. Note if the broker hosting the web service is on a different machine to this broker, or is using a non-default port number, or both, amend this URL as appropriate.
    3. Click Response Message Parsing:
      • For Message domain, select MRM from the list.
      • For Message set, select WSCLIENT_MS1 from the list.
      • For Message type, select Envelope from the list.
      • For Message format, select XML1 from the list.
    4. Save and close the Properties dialog.
  8. Customize the Compute1 node:
    1. Right-click the Compute1 node, and click Open ESQL.
    2. Type the following ESQL between the BEGIN and END statements for this module. Use Content Assist (Ctrl + space) to select keywords. A DECLARE NAMESPACE statement similar to that commented on the first line should be generated when Content Assist is used for the first time to select the SOAP Body element.
      --DECLARE tns NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
      --DECLARE ns NAMESPACE 'http://www.brokersamplewshost.ibm.com';
      
          CALL CopyMessageHeaders();
      
      -- Output is MQ, so remove HTTP headers
          SET OutputRoot.HTTPResponseHeader = NULL;
              
      -- Output is CWF, so set the target message set properties
      
      	SET OutputRoot.Properties.MessageType = 'msg_tagIA81CONF';
      	SET OutputRoot.Properties.MessageFormat = 'CWF1';
      
      -- Create an MQMD and restore it to the saved values
      
      	CREATE NEXTSIBLING OF OutputRoot.Properties DOMAIN 'MQMD';
          SET OutputRoot.MQMD = Environment.MQMD;
      
      -- Build message to be sent
      
      	SET OutputRoot.MRM.MessageId - InputBody.tns:Body.ns:IA81CONFOUT.MessageId;
      	SET OutputRoot.MRM.OrderNumber = InputBody.tns:Body.ns:IA81CONFOUT.OrderNumber;
      	SET OutputRoot.MRM.ItemReference = InputBody.tns:Body.ns:IA81CONFOUT.ItemReference;
      	SET OutputRoot.MRM.ItemQuantity = InputBody.tns:Body.ns:IA81CONFOUT.ItemQuantity;
      	SET OutputRoot.MRM.CustomerNumber = InputBody.tns:Body.ns:IA81CONFOUT.CustomerNumber;
      	SET OutputRoot.MRM.DeliveryRef = InputBody.tns:Body.ns:IA81CONFOUT.DeliveryRef;
      	SET OutputRoot.MRM.Confirm = InputBody.tns:Body.ns:IA81CONFOUT.Confirm;						
      	SET OutputRoot.MRM.filler1 = InputBody.tns:Body.ns:IA81CONFOUT.filler1;	
      
      	RETURN TRUE;
  9. Customize the MQReply node:
    1. There is no customization to be done.
  10. Close WSCLIENT_WSCLIENT1.esql, saving the contents.
  11. Close WSCLIENT_WSCLIENT1.msgflow, saving the contents.

Back to sample home