Building the Web Service sample

The Web Service sample has two parts:

Building the Web Service Host sample

If you do not want to do this, a completed message set project and message flow project are supplied with this sample.

To build the Web Service Host sample:

  1. Create a message set. This will serve both the Web service format message (XML) and the legacy format (CWF).
    1. Start the Message Brokers Toolkit.
    2. Ensure that you are in the Broker Application Development perspective.
    3. Click File > New > Message Set Project.
    4. Set Project name to WSHOST_MSP1, then click Next.
    5. Set Message Set Name to WSHOST_MS1.
    6. Select Use namespaces, then click Next.
    7. Select Custom Wire Format Name and XML Wire Format Name, then click Finish.
    8. Close messageset.mset, saving the contents.
  2. Import a C header file. This maps to the input and output message of the legacy application.
    1. Click File > Import > File System > Next.
    2. Browse to select legacyservice.h from project WSHOST_LEGACY.
    3. Set Into folder to WSHOST_MSP1, then click Finish
    4. Create a Broker message definition file from the C header file:
      1. In the Resource Navigator, right-click legacyservice.h, then click New > Message Definition File.
      2. The radio button for C header file should be preselected. If not, select it then click Next
      3. Within project WSHOST_MSP1, legacyservice.h should be preselected. If not, select it then click Next.
      4. In the Message sets pane, expand WSHOST_MSP1 and select WSHOST_MS1.
      5. Select Use target namespace and enter http://www.brokersamplewshost.ibm.com as the URL, then click Next.
      6. In the Source structures pane, click tagIA81CONF, click the > button, then click Select all > Finish.
    5. Close legacyservice.mxsd, saving the contents.
  3. Build a SOAP message definition.
    1. In the Resource Navigator, right-click message set WSHOST_MS1 then click New > Message Definition File.
    2. Click the radio button IBM supplied message, then click Next.
    3. In the IBM supplied messages pane, select message ibm\soap\envelope\soapenv11.xsd, then click Next.
    4. Expand WSHOST_MSP1 and select WSHOST_MS1, then click Next.
    5. In Select Global Elements from which to create messages, ensure no elements are selected, then click Finish.
    6. Close soapenv11.mxsd, saving the contents
    7. Notice that Envelope is created as a message automatically.

      A number of 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 and they can be ignored.

  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 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 populated from the C header file.

    1. Open legacyservice.mxsd.
    2. In the Outline view, right-click Elements and Attributes and click Add Global Element.
    3. Change the name of the Element to IA81CONFIN and press Enter.
    4. Select the Type cell for the IA81CONFIN Element. Choose (More...) from the list.
    5. Select tagIA81CONF and click OK.
    6. In the Outline view, right-click Messages and click Add Message From Global Element.
    7. Select tns:IA81CONFIN from the pulldown list and press Enter.
    8. In the Outline view, right-click Elements and Attributes and click Add Global Element.
    9. Change the name of the Element to IA81CONFOUT and press Enter.
    10. Select the Type cell for the IA81CONFOUT Element. Choose (More...) from the list.
    11. Select tagIA81CONF and click OK.
    12. In the Outline view, right-click Messages and click Add Message From Global Element.
    13. Select tns:IA81CONFOUT from the pulldown list and press Enter.
    14. Close legacyservice.mxsd, saving the contents.
    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, enter cat1 then click Next.
    20. In the top pane, select IA81CONFIN and IA81CONFOUT (press and hold the CTRL key 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. Select message set WSHOST_MS1 within message set project WSHOST_MSP1, then click Next.
    3. Select WSHOST_MSP1, then click Create New Folder.
    4. Enter wsdl as the folder name, then click OK.
    5. Check that the Single radio button 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 an HTTP request, invokes the legacy application using MQ, and routes information from the legacy application's response to the HTTP requestor.
    1. Click File > New > Message Flow Project.
    2. Set Project name to WSHOST_MFP1, then click Next.
    3. In the "Referenced projects" pane, select WSHOST_MSP1 then click Finish.
    4. In the Resource Navigator, right-click WSHOST_MFP1, then click New > Message Flow.
    5. Set Schema to WSHOST_MFP1.
    6. Set Name to WSHOST_WSHOST1, then click Finish.
    7. Display the palette (if hidden), then put the following nodes on the Message Flow canvas:
      • 1 HTTPInput node
      • 3 Compute nodes
      • 2 MQOutput nodes
      • 1 MQGet node
      • 1 MQInput node
      • 1 HTTPReply node
    8. Click Connection on the palette, then connect the following nodes and terminals:
      • HTTPInput (out) - Compute (in)
      • Compute (out) - MQOutput (in)
      • MQOutput (out) - Compute1 (in)
      • Compute1 (out) - MQOutput1 (in)
      • MQInput (out) - MQGet (in)
      • MQGet (out) - Compute2 (in)
      • Compute2 (out) - HTTPReply (in)
  7. It might help your understanding if you rename some of the nodes. To rename a node, right-click the node then click Rename. Suggested names are:
  8. Customize the HTTPInput node:
    1. Right-click the HTTPInput node, and click Properties.
    2. Select Basic, and set URL Selector to /samplebrokerwshost.
    3. Select Default:
      • For Message Domain, select MRM from the drop-down list.
      • For Message Set, select WSHOST_MS1 from the drop-down list.
      • For Message Type, enter Envelope.
      • For Message Format, select XML1 from the drop-down list.
    4. Click OK.
  9. Customize the Compute node:
    1. Right-click the Compute 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. DECLARE NAMESPACE statements similar to those commented on the first two lines should be generated when content-assist is used 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;
  10. Customize the MQOutput (MQOutput to legacy) node:
    1. Right-click the MQOutput 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. Select Advanced and set Transaction Mode to Yes.
    5. Set Message Context to Default.
    6. Select Request, and select the check box for Request.
    7. Set Reply-to Queue to WSHOST1_IN1, then click OK.
  11. 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 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';
      
      -- 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;
  12. Customize the MQOutput1 (MQOutput store HTTP state) node:
    1. Right-click the MQOutput1 node, and click Properties.
    2. Select Basic, and set Queue Name to WSHOST1_STATE1.
    3. Select Advanced and set Transaction Mode to Yes.
    4. Set Message Context to Default.
    5. Click OK.
  13. Customize the MQInput (MQInput from legacy) node:
    1. Right-click the MQInput node, and click Properties.
    2. Select Basic, and set Queue Name to WSHOST1_IN1.
    3. Select Default:
      • For Message Domain, select MRM from the drop-down list.
      • For Message Set, select WSHOST_MS1 from the drop-down list.
      • For Message Type, enter msg_tagIA81CONF.
      • For Message Format, select CWF1 from the drop-down list.
    4. Click OK.
  14. Customize the MQGet (MQGet stored HTTP state) node:
    1. Right-click the MQGet node, and click Properties.
    2. Select Basic, and set Queue Name to WSHOST1_STATE1.
    3. Select Default:
      • For Message Domain, select MRM from the drop-down list.
      • For Message Set, select WSHOST_MS1 from the drop-down list.
      • For Message Type, enter Envelope.
      • For Message Format, select XML1 from the drop-down list.
    4. Select Advanced:
      • For Generate Mode, select Message and LocalEnvironment from the drop-down list.
      • For Copy Message, select Copy Entire Message from the drop-down list.
    5. Select Request, and select the check box for Get by Correlation ID.
    6. Select Result, and set Output Data Location to OutputLocalEnvironment.
    7. Click OK.
  15. Customize the Compute2 node:
    1. Right-click the Compute2 node, and click Properties.
    2. Select Basic, and set Compute Mode to LocalEnvironment and Message.
    3. Click OK (to allow HTTP context to be passed to HTTPReply node)
    4. Right-click the node, and select Open ESQL.
    5. Code 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;
  16. Close WSHOST_WSHOST1.esql, saving the contents.
  17. Close WSHOST_WSHOST1.msgflow, saving the contents.
  18. If you intend to run the legacy application on a different WebSphere MQ queue manager to the broker, you need to 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

If you do not want to do this, a completed message set project and message flow project are supplied with this sample.

To build the Web Service Client sample:

  1. Create a message set. This will serve both the Web service format message (XML) and the legacy format (CWF).
    1. Start the Message Brokers Toolkit.
    2. Ensure that you are in the Broker Application Development perspective.
    3. Click File > New > Message Set Project.
    4. Set Project name to WSCLIENT_MSP1, then click Next.
    5. Set Message Set Name to WSCLIENT_MS1.
    6. Select Use namespaces, then click Next.
    7. Select Custom Wire Format Name and XML Wire Format Name, then click Finish.
    8. Close messageset.mset, saving the contents.
  2. Import a C header file. This provides the input and output message definitions of the legacy applications.
    1. Copy file legacyservice.h from project WSHOST_LEGACY, and paste it into project WSCLIENT_MSP1.
    2. Create a Broker message definition file from the C header file:
      1. In the Resource Navigator, right-click legacyservice.h, then click New > Message Definition File.
      2. The radio button for C header file should be preselected. If not, select it then click Next
      3. Within project WSCLIENT_MSP1, legacyservice.h should be preselected. If not, select it then click Next.
      4. In the Message sets pane, expand WSCLIENT_MSP1 and select WSCLIENT_MS1, then click Next.
      5. In the Source structures pane, click tagIA81BUY, click the > button, click tagIA81CONF, click the > button, then click Select all > Finish.
    3. Close legacyservice.mxsd, saving the contents.
  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 Broker message definition file from the WSDL:
      1. In the Resource Navigator, 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 select 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 as input a WebSphere MQ message, builds a web service request and sends the request using HTTP. The HTTP reply is received, and a WebSphere MQ reply message is sent.
    1. Click File > New > Message Flow Project.
    2. Set Project name to WSCLIENT_MFP1, then click Next.
    3. In the "Referenced projects" pane, select WSCLIENT_MSP1, then click Finish.
    4. In the Resource Navigator, right-click WSCLIENT_MFP1, then click New > Message Flow.
    5. Set Schema to WSCLIENT_MFP1.
    6. Set Name to WSCLIENT_WSCLIENT1, then click Finish.
    7. Display the palette (if hidden), then put the following nodes on the Message Flow canvas:
      • 1 MQInput node
      • 2 Compute nodes
      • 1 MQReply node
      • 1 HTTPRequest node
    8. Click Connection on the palette, then connect the following nodes and terminals:
      • MQInput (out) - Compute (in)
      • Compute (out) - HTTPRequest (in)
      • HTTPRequest (out) - Compute1 (in)
      • Compute1 (out) - MQreply (in)
  5. Customize the MQInput (MQInput from legacy) node:
    1. Right-click the MQInput node, and click Properties.
    2. Select Basic, and set Queue Name to WSCLIENT1_IN1.
    3. Select Default:
      • For Message Domain, select MRM from the drop-down list.
      • For Message Set, select WSCLIENT_MS1 from the drop-down list.
      • For Message Type, select msg_tagIA81BUY from the drop-down list.
      • For Message Format, select CWF1 from the drop-down list.
    4. Click OK.
  6. Customize the Compute node:
    1. Right-click the Compute 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. DECLARE NAMESPACE statements similar to those commented on the first two lines should be generated when content-assist is used 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 Properties.
    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. Select Default:
      • For Message Domain, select MRM from the drop-down list.
      • For Message Set, select WSCLIENT_MS1 from the drop-down list.
      • For Message Type, select Envelope from the drop-down list.
      • For Message Format, select XML1 from the drop-down list.
    4. Click OK.
  8. 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 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.

Main Page icon   Back to sample home