Building the Web Service sample
The Web Service sample has two parts:
- A Web Service Host sample
- A Web Service Client sample
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:
- 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):
- Start the Message Brokers Toolkit.
- Switch to the Broker Application Development perspective.
- Click File > New > Message Set.
- Set Message set name to WSHOST_MS1.
- Set Message set project name to WSHOST_BUILD_MSP1, then click Next.
- Click XML documents and Binary data, then click Finish.
- Save and close messageSet.mset.
- Import a C header file, which maps to the input and output message of the legacy application:
- Click File > Import > File system, then click Next.
- Browse to find project WSHOST_LEGACY1, then click Select All.
- Set Into folder to WSHOST_BUILD_MSP1, then click Finish.
- Create a message definition file from the C header file:
- In the Broker Development view, right-click legacyservice.h, then click New > Message Definition File From > C Header File.
- Set Message set to /WSHOST_BUILD_MSP1/WSHOST_MS1.
- Set Target namespace to http://www.brokersamplewshost.ibm.com, then click Next.
- In the Source structures pane, click tagIA81CONF, click the > button, then click Select all > Finish.
- Save and close legacyservice.mxsd.
- Build a SOAP message definition:
- In the Broker Development view, right-click message set WSHOST_MS1, then click New > Message Definition File From > IBM Supplied Message.
- In the IBM supplied messages pane, select message ibm\soap\envelope\soapenv11.xsd, then click Next.
- Expand WSHOST_BUILD_MSP1, select WSHOST_MS1, then click Finish.
- Save and close soapenv11.mxsd.
- 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.
- 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:
- In the Broker Development view, double-click legacyservice.mxsd.
- In the Outline view, right-click Elements and Attributes, then click Add Global Element.
- Change the name of the new element to IA81CONFIN, then press Enter.
- In the Type cell for the IA81CONFIN element, click (More...) from the list.
- Click tagIA81CONF, then click OK.
- In the Outline view, right-click Messages, then click Add Message From Global Element.
- Click tns:IA81CONFIN from the list, then press Enter.
- In the Outline view, right-click Elements and Attributes, then click Add Global Element.
- Change the name of the element to IA81CONFOUT, then press Enter.
- In the Type cell for the IA81CONFOUT element, click (More...) from the list.
- Click tagIA81CONF and click OK.
- In the Outline view, right-click Messages and click Add Message From Global Element.
- Click tns:IA81CONFOUT from the list and press Enter.
- Save and close legacyservice.mxsd.
- Click File > New > Message Category File.
- Set Category Kind to wsdl.
- Set Category Usage to wsdl:requestresponse, then click Next.
- Select message set WSHOST_MS1 within message set project WSHOST_MSP1.
- In the File name field, type cat1 then click Next.
- In the top pane, select IA81CONFIN and IA81CONFOUT (press and hold ctrl to make multiple selections).
- 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).
- In the bottom pane, select IA81CONFIN, then click Finish.
The new message category file is created.
- Generate WSDL:
- Click File > New > WSDL Definition > Next.
- Click message set WSHOST_MS1 within message set project WSHOST_MSP1, then click Next.
- Click WSHOST_MSP1, then click Create New Folder.
- Type wsdl as the folder name, then click OK.
- Ensure that Single is selected, then click Next.
- In the "Specify WSDL details" pane, ensure that Style is set to document, then click Next.
- In the "Select categories" pane, click Select All > Next.
- In the Bindings pane, click SOAP/HTTP > Next.
- In the "Service properties" pane, set Port Address
to http://localhost:7080/samplebrokerwshost then click Finish.
- 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:
- Click File > New > Message Flow Project.
- Set Project name to WSHOST_BUILD_MFP1, then click Next.
- In the "Referenced projects" pane, select WSHOST_BUILD_MSP1 then click Finish.
- In the Broker Development view, right-click WSHOST_BUILD_MFP1, then click New > Message Flow.
- Set Message flow name to WSHOST_WSHOST1.
- Set Schema to WSHOST_MFP1, then click Finish.
- 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 |
- 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 |
- Customize the HTTP Input node:
- Right-click the HTTP Input node, and click Properties.
- Click Basic, and set Path suffix for URL to /samplebrokerwshost.
- 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.
- Save and close the Properties dialog.
- Customize the Compute node:
- Right-click the Compute node, and click Open ESQL.
- 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;
- Customize the MQOutput to legacy node:
- Right-click the MQOutput to legacy node, and click Properties.
- 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.
- Set Queue name to WSHOST1_OUT1.
- Click Advanced and set Transaction mode to Yes.
- Set Message context to Default.
- Click Request, and select Request.
- Set Reply-to queue to WSHOST1_IN1, then save and close the Properties dialog.
- Customize the Compute1 node:
- Right-click the Compute1 node, and click Open ESQL.
- 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;
- Customize the MQOutput store HTTP state node:
- Right-click the MQOutput store HTTP state node, and click Properties.
- Click Basic, and
set Queue manager name to WSHOST1_STATE1.
- Click Advanced and set Transaction mode to Yes.
- Set Message context to Default.
- Save and close the Properties dialog.
- Customize the MQInput from legacy node:
- Right-click the MQInput from legacy node, and click Properties.
- Click Basic, and set Queue name to WSHOST1_IN1.
- 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.
- Save and close the Properties dialog.
- Customize the MQGet stored HTTP state node:
- Right-click the MQGet stored HTTP node, and click Properties.
- Click Basic, and set Queue name to WSHOST1_STATE1.
- 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.
- Click Advanced:
- For Generate mode, select Message and LocalEnvironment from the list.
- For Copy message, select Copy Entire Message from the list.
- Click Request, and select the check box for Get by correlation ID.
- Click Result, and set Output data location to OutputLocalEnvironment.
- Save and close the Properties dialog.
- Customize the Compute2 node:
- Right-click the Compute2 node, and click Properties.
- Click Basic, and set Compute mode to LocalEnvironment and Message.
- Save and close the Properties dialog.
- Right-click the node, and click Open ESQL.
- 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;
- Save and close WSHOST_WSHOST1.esql.
- Save and close WSHOST_WSHOST1.msgflow.
- 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:
- 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).
- Start the Message Brokers Toolkit.
- Switch to the Broker Application Development perspective.
- Click File > New > Message Set.
- Set Message set name to WSCLIENT_MS1.
- Set Message set project name to WSCLIENT_BUILD_MSP1,
then click Next.
- Click XML documents and Binary data, then click Finish.
- Save and close messageSet.mset.
- Import a C header file which maps the input and output message of the legacy application:
- Copy file legacyservice.h from project WSHOST_LEGACY1,
and paste it into project WSCLIENT_BUILD_MSP1.
- Create a message definition file from the C header file:
- In the Broker Development view, right-click legacyservice.h,
then click New > Message Definition File From > C Header File.
- Set Message set to /WSCLIENT_BUILD_MSP1/WSCLIENT_MS1, then click Next.
- In the Source structures pane,
click tagIA81BUY,
click the > button,
click tagIA81CONF,
click the > button,
then click Select all > Finish.
- Save and close legacyservice.mxsd.
- Import the WSDL for the web service.
- Click File > Import > File System > Next.
- Browse to select directory wsdl
from project WSHOST_MSP1.
- Set Into folder to WSCLIENT_MSP1,
then click Finish
- Create a message definition file from the WSDL:
- In the Broker Development view, right-click WSHOST_MS1Service.wsdl,
within the wsdl directory of project
WSCLIENT_MSP1
then click New > Message Definition File.
- The radio button for WSDL file should be preselected.
If not, select it then click Next.
- Within project WSCLIENT_MSP1, WSHOST_MS1Service.wsdl should be preselected.
If not, select it then click Next.
- In the Message sets pane, expand WSCLIENT_MSP1
and click WSCLIENT_MS1.
- In the namespace pane, set the namespace prefix for namespace http:www.brokersamplewshost.ibm.com
to wshost then click Next.
- You are shown a list of files which will be generated. Click Finish.
- 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:
- Click File > New > Message Flow Project.
- Set Project name to WSCLIENT_BUILD_MFP1,
then click Next.
- In the "Referenced projects" pane, select WSCLIENT_BUILD_MSP1,
then click Finish.
- In the Broker Development view, right-click WSCLIENT_BUILD_MFP1,
then click New > Message Flow.
- Set Message flow name to WSCLIENT_WSCLIENT1.
- Set Schema to WSCLIENT_MFP1, then click Finish.
- 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 |
- 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 |
- Customize the MQInput from legacy node:
- Right-click the MQInput from legacy node, and click Properties.
- Click Basic, and set Queue name
to WSCLIENT1_IN1.
- 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.
- Save and close the Properties dialog.
- Customize the Compute node:
- Right-click the Compute node, and click Open ESQL.
- 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;
- Customize the HTTPRequest node:
- Right-click the HTTPRequest node, and click the Properties dialog.
- 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.
- 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.
- Save and close the Properties dialog.
- Customize the Compute1 node:
- Right-click the Compute1 node, and click Open ESQL.
- 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;
- Customize the MQReply node:
- There is no customization to be done.
- Close WSCLIENT_WSCLIENT1.esql, saving the contents.
- Close WSCLIENT_WSCLIENT1.msgflow, saving the contents.
Back to sample home