Integrating applications using WebSphere Business Integration Message Broker V5: Part 2: Message set development Introduction ...................................................................................................................................... 1 Message set .................................................................................................................................... 1

Web Order Application Sample: message sets .......................................................................... 2 WebSphere Business Integration Message Broker Application Development perspective............ 2 Creating message sets.................................................................................................................... 5

New Message Set wizard............................................................................................................ 5 Message set editor ...................................................................................................................... 7

Creating a message definition ......................................................................................................... 9 New Message Definition wizard .................................................................................................. 9 Creating a new message definition ........................................................................................... 10 Importing from a COBOL file..................................................................................................... 12 Command line importing ........................................................................................................... 15

Editing message definitions........................................................................................................... 16 Message definition referencing...................................................................................................... 18

Include....................................................................................................................................... 18 Import ........................................................................................................................................ 19

Message definition preferences..................................................................................................... 20 Conclusion ..................................................................................................................................... 21 References .................................................................................................................................... 22

Introduction This is the second article in a six-part series on WebSphere® Business Integration Message Broker V5. This article, Part 2: Message set development, describes the concept of message sets, logical and physical representation of messages. It describes how to create the messages used in the Web order processing application sample from XML Schema, COBOL copy book and the modification and maintenance of messages using the spreadsheet-like message editor.

Message set A message set provides a business context for a set of messages. It groups the message definition files and is a unit of deployment and versioning in WebSphere Business Integration Message Broker.

A message definition file contains one or more messages and the constructs that describe the logical and physical format of the message. WebSphere Business Integration Message Broker message model is used for modeling the messages; it is comprised of:

o Logical Model: It describes the logical structure of messages. The logical model is platform and language neutral and it uses an XML Schema to define the structural contents of messages.

o Physical representation of the logical model: It describes how the messages are laid on the wire. It is commonly know as wire formats in WebSphere Business Integration Message Broker. The same logical structure of a message can be represented in many wire formats. The physical representation (wire format) properties are serialized as XML Schema annotations on the logical constructs of the message. The default values for the physical representations are kept at message set level in a messageSet.mset file

1

described later in the article. WebSphere Business Integration Message Broker supports following wire formats:

• Custom Wire Format (CWF): This physical representation of a message has a number of data elements adjacent to each other that do not have any delimiters. Without knowledge of the message structure, you cannot distinguish one element form the next. To interpret the values of the individual elements you have to know the order and length of each element. A CWF typically maps to the in memory layout of a COBOL or C language data structure and is typically used for communicating with legacy back ends

• XML Wire Format: typically used by new applications for communicating with business partners using XML.

• Tagged Delimited String (TDS) Wire Format: It is designed to model messages that consist of text strings. It allows associating a tag with the element of a message and a delimiter to be used between the message elements. Examples of TDS messages are ACCORD, AL3, EDIFACT, SWIFT and X12 messaging standards used widely in the banking, insurance and travel industry.

Large message sets can contain several message definition files. This keeps the individual message definition files to a manageable size, making them faster and easier to work with.

Web Order Application Sample: message sets

Web Order Application Sample uses the following message sets:

o WebOrderMessageSet o Contains a set of messages used for interacting with Credit Card Processing

System. TDS format is used for exchanging messages with this system. o Supports TDS and XML wire formats.

o ProductInventoryMessageSet o Contains a set of messages used for interacting with the Inventory Control

Systems and Suppliers for placing new orders for the part items. o Supports CWF and XML wire formats. o Messages targeted for the legacy Inventory Control Systems are created by

importing a COBOL copy book. o Messages exchanged with the suppliers are in the XML format.

o PurchaseOrderMessageSet o Contains a set of messages pertaining to customer information and the purchase

order requests. o Supports 2 variations of XML wire formats. o Web order processing application receives these messages in XML format from

the front end application. Now we will describe the WebSphere Business Integration Message Broker tools used to create Message Set and the message definitions. WebSphere Business Integration Message Broker tooling provides a custom “Application Development Perspective” for developing message set and broker applications.

WebSphere Business Integration Message Broker Application Development perspective The Broker Application Development perspective (hereafter referred to as the Broker AD perspective) is the default perspective when you first start the WebSphere Business Integration Message Broker V5 toolkit.

2

Typically, you carry out the following tasks in this perspective:

• Develop message sets and message flows. • Deploy message flows and message sets using the Run on Server utility. This supports

rapid application development (RAD), and is also referred to as single-click deployment. • Enqueue and dequeue messages to the queue. This is particularly useful when you are

debugging message flows. The following views are provided to support you in these tasks:

Resource Navigator view Displays a hierarchical view of the following message flow and message set resource files:

• Message set projects • Message sets • Message definition files • Message category files • Message flow projects • Message flows • ESQL files • Mapping files

You can open any of these resources for editing using specialized editors, except project files.

Editor area Editors are launched in the editor area when you double-click on a resource file in the Resource Navigator view. WebSphere Business Integration Message Broker provides following specialized editors to work with the content of message flow and message set files.

• Message Set Editor – edits messageSet.mset files • Message Definition Editor – edits files with the mxsd extension • Message Category Editor – edits files with the category extension • Message Flow Editor – edits files with msgflow extension • ESQL Editor – edits files with esql extension • Message Flow Mapping Editor – edits files with mfmap extension

In this article, we will describe only the editors used for message set development. .

3

Figure 1: Broker Application Development Perspective -- Resource Navigator

The above figure shows what is displayed in the Broker AD Perspective’s Resource Navigator. The top-level objects displayed in the navigator are the Message Set and Message Flow projects. Under the Message flow project , it shows the packages containing message flows and ESQL files The name of the package is derived from the name space URI associated with the message flow or the ESQL files. Under the Message Set Project , it shows the Message Set (which is a folder immediately under the project) containing messageSet.mset file and packages containing message definition files and message category files. The package name is derived from the target name space declaration contained in the message definition file. If the message definition has no target namespace then it will be under the (default) package. The algorithm, for deriving package name from target namespace takes the domain name specified in the target namespace and reverses it; the algorithm then appends rest of the name tokens from target namespace as dot separated lower case names to the package name. As the above diagram shows the message definition file CreditInquiry.mxsd having a target namespace http://www.ibm.com/WebOrderMessages/CreditInfo, appears under the package com.ibm.www.webordermessages.creditinfo which maps to the directory structure <Project>/com/ibm/www/webordermessages/creditinfo.

4

Creating message sets A message set lives in a message set project. A message set project is a specialized project in which you create and maintain all the resources associated with exactly one message set. The content of a message set project is a single message set folder; the name of which identifies the name of the message set. The message set folder contains messageSet.mset file and the message definitions files. The messageSet.mset file contains message set identifier and the default values for all of the wire formats supported in the message set. Additionally you can create folders within a message set project to store additional resources like COBOL Copybooks, C headers and XML Schemas.

New Message Set wizard

A message set project can be created by invoking Message Set Project. To invoke it, click “File=>New=>Message Set Project” wizard. The Message Set Project wizard allows you to create a new Message Set Project along with an option to create a Message Set. If you wish to only create a Message Set Project, then you can just fill in the first page in the wizard and click Finish.

Figure 2: Create New Message Set Project – wizard page 1

The figure above shows the first page in the New Message Set Project wizard. The project name is mandatory and will be the name of the new message set project.

5

Figure 3: Create New Message Set Project -- wizard Page 2

The figure above shows the different settings that can be made in the second page of the new message set project wizard. If you want to enable namespace support now, select the checkbox Use namespaces. This allows the use of namespaces when you are defining message model objects. Namespaces provide a simple mechanism for qualifying element and attribute names used in message definition files by associating them with namespaces identified by URI references.

A single XML instance document can contain elements and attributes that are defined for and possibly used by multiple applications. Two different elements or attributes within the same document might require the same name. Individual applications need to be able to recognize the elements and attributes relevant to their domain. In circumstances such as this, the definitions can be distinguished from each other by qualifying each element with a different namespace. This avoids problems of name collision and mistaken recognition. Defining a target namespace for XML Schema allows global entities (elements, attributes, groups and types) and optionally local entities defined within XML Schema to be qualified by the target namespace. This assists in the development of a library of XML Schemas which can be developed and managed independently by different groups/applications without worrying about the name clashes with the definitions defined within other XML Schemas. The other field that you can optionally select is the “Base Message Set” field. Selecting a base message set will copy the contents of the base message set into the newly created message set.

6

Figure 4: Create New Message Set Project – wizard page 3

The last page of the new message set project wizard allows you to create an initial CWF, XML and TDS Formats. For the ProductInventoryMessageSet, select Custom Wire Format Name checkbox and change the CWF name to be “WINNT”. This will create a new Custom Wire Format in the ProductInventoryMessageSet message set with name WINNT.

Message set editor

The message set editor can be launched on messageSet.mset file. It consists of a single properties editor, which is used to set global settings in the message set and also to create different physical formats (CWF, XML Wire format, TDS format) that will be used by the message definitions within the message set.

7

Figure 5: Message Set Editor

New physical formats are created by right clicking on the Physical properties node within the Properties Hierarchy and selecting one of the following options:

• Add Custom Wire Format • Add XML Wire Format • Add Tagged/Delimited String Format

After adding a new physical format all of the pre-defined defaults are set within the format.

Figure 6: Message Set Editor -- WINNT Custom Wire Format default settings

8

The above figure shows how all of the default properties are set on the WINNT Custom Wire Format after it is created. Changing the Use default dateTime format property will allow all of the dateTime elements in the given message set to use the new dataTime format. At any time you can revert back to the original defaults by right clicking on the WINNT custom wire format node in the Properties Hierarchy and selecting “Apply default physical format settings”.

Creating a message definition Message definitions contain the logical and physical definition of the message.

New Message Definition wizard

Message definitions can be created by several different methods, which consist of the following: • New Message definition • XML schema file • XML DTD file • C header file • COBOL file

Create a message definition by invoking the Message Definition Wizard. To invoke it, click File=>New=>Message Definition wizard.

9

Figure 7: New Message Definition -- wizard page 1

Several of the importers populate the physical model during the import, which are illustrated in the following table: Source Populated Physical Format XML Schema file All XML wire formats XML DTD file All XML wire formats C header file All Custom wire formats COBOL file All Custom wire formats

Creating a new message definition

Select the “Create a new message definition file” radio button to create a new empty message definition file. This message definition will only contain namespace information. The next page

10

(after you select the radio button mentioned above) will allow you to choose a new file name. At this point you should edit the Name field to be “CreditInquiry.mxsd”. If you click Finish at this point, it will create a new message definition in the no targetNamespace.

Figure 8: New Message Definition -- wizard page 2

However for the “CreditInquiry.mxsd” message definition, we will navigate to the third page to specify a target namespace that is shown below:

11

Figure 9: New Message Definition -- wizard page 3

In the above figure, we have chosen this message definition file to be in the http://www.ibm.com/WebOrderMessages/CreditInfo namespace. This means that all of the global definitions (complexTypes, simpleTypes, groups, attributeGroups, attributes and elements) within this file will belong to the http://www.ibm.com/WebOrderMessages/CreditInfo namespace. At this point you can also give a prefix to the schema for schemas. The default is normally not to prefix the schema for schemas when we are defining a new namespace for the message definition.

Importing from a COBOL file

To illustrate how to import a COBOL file into a message set, we will use the Inventory.cbl COBOL file, which will be imported into the ProductInventoryMessageSet message set.

12

*************************************************************** ** Application: Inventory ** ** COBOL declaration of Logical MRM message *************************************************************** 01 UpdateItemInventory. 03 TranType PIC X(3). 88 TranUpdate VALUE "UPD". 88 TranDelete VALUE "DEL". 03 TransDate PIC 9(8). 03 Items. 05 ItemNo PIC X(10). 05 ItemQty PIC S9(5). 01 StockItem. 03 TranType PIC X(3). 88 TranUpdate VALUE "UPD". 88 TransAdd VALUE "ADD". 88 TransDelete VALUE "DEL". 88 TransRead VALUE "RET". 03 ItemDetails. 05 ItemNo PIC X(10). 05 ItemDescr PIC X(20). 05 ItemQty PIC S9(5). 05 ItemPrice PIC S9(3)V99. Select the “COBOL file” radio button to create a new message definition file from a COBOL file. There will be several options that can be customized through the wizards while creating a new message definition file from a COBOL file. The COBOL importer will read and parse the COBOL file and if there are no errors during the parse, it will display the top level elements (that is, COBOL elements defined at 01 level) that you may want to import and additionally create message based on such elements. The following shows the top-level structures (01 level element) UpdateItemInventory , StockItem found in the inventory.cbl file that we are going to import and create message definitions based on these structures. We optionally can choose to prefix the imported structures with a user defined prefix to prevent name clashing with the structures that may already be present in the message set.

13

Figure 10: New Message Definition from COBOL -- Select top level structures

The last page of this wizard allows you to specify compile options for importing the COBOL copy book. COBOL importer supports only those set of compile option, shown in the following diagram, which affect in-memory layout and hence format of data on the wire. When you select a particular platform from the drop down box Source platform, the compile options that are most commonly used for that platform are automatically selected. You have the option to override the selection by explicitly selecting the appropriate radio button to suit your requirement. For further information on the compile options and other options supported by the COBOL importer, please see WebSphere Business Integration Message Broker Online help.

14

Figure 11: New Message Definition from COBOL -- Select Compile options

Command line importing

Batch importing is supported by invoking the command line importer “mqsicreatemsgdefs.exe”. The mqsicreatemsgdefs.exe takes the following arguments: Syntax: mqsicreatemsgdefs -data Workspace location (optional) -p <messageSetProjectName>, will be created if it does not exist -base <baseMessageSetProjectName\baseMessageSetName> (optional) -d <sourceFilesDirectory> (absolute/relative) containing C/COBOL/DTD/XSD files -rmp Replace message set project if it already exists (optional) -rmd Replace message definitions if they already exist (optional) -ns Namespace aware if creating new message set (optional) -msg Create messages from complex global elements (optional)

15

-v Produce verbose report (optional) -opt <importPropertiesFilePath> (absolute/relative) (optional) -log <reportFileName> (optional) The command line importer uses a default options file called mqsicreatemsgdefs.xml that is stored in the com.ibm.etools.msg.importer.cmdline plugin. The options file contains all of the options that the COBOL, C, XML Schema and DTD importer wizards use. Any changes to the default settings should be made in a local copy of the options file and then passed to the command line importer.

Editing message definitions The message definition editor can be launched on any file with extension “mxsd” within a message set. It consists of an outline view, overview editor, and properties editor. This editor is used to construct message definitions and edit both the logical and physical properties within the message definition.

Figure 12: Message Definition Editor – Overview Tab

The figure above shows the different views and tabs provided by the message definition editor. All objects within the Outline View tree and Overview editor tree are identified by a label and icon. If the object is a reference, it will display an arrow icon in the top left corner of the objects icon. In the figure above, you can see that there is an element reference “po:comment” under the purchaseOrder message, which has the arrow icon in the top left corner.

16

Figure 13: Message Definition Editor -- Properties Tab

Outline view The outline view displays a hierarchical set of objects that will help create message definitions. This contains Messages, Types, Groups, "Elements and Attributes". Selecting an object in the outline view causes the overview editor and properties editor to be updated. The outline view is typically used to navigate the entire message definition within a single view.

Overview editor The overview editor displays a hierarchical subset of objects that will help create message definitions. The subset depends on which object is selected in the outline view. It is the first tab in the message definition editor. The difference between the overview editor and the outline view is that it only lets you change some of the most common properties. These properties could consist of changing the min/maxOccurs of an element, changing name of the element or its type. Selecting an object in the overview editor causes the properties editor to be updated.

Properties editor The properties editor lets you change a set of properties for the selected object in the outline view or overview editor. This editor is the second tab in the message definition editor. The properties editor consists of a Properties Hierarchy that separates the logical properties from the physical properties. When selecting objects within a message definition file, you will see two actions called Open Declaration and Open Type Definition that will help you navigate to referenced objects within the same message definition or referenced message definitions.

17

Open declaration The open declaration action can be invoked on any object that references a global object. This consists of element references, attribute references, group references, and attribute group references. If the resolved reference exists in a different message definition file, then that message definition file will be opened and the resolved object will be selected. In addition to the regular methods for action invocation, Open Declaration action can be invoked with the <F3> key.

Open type definition The open type definition action can be invoked on an elements or attributes that have a type definition that is not one of the built in types (that is, xsd:string , xsd:int...). In addition to the regular methods for action invocation, Open Type Definition action can be invoked with the <F4> key.

Message definition referencing There are two possible ways you can reference message constructs (global element, types, groups, and so forth) defined in another message definition file. Since logical model of the message definition file is XML schema, we use the XML schema semantics for includes and imports.

Include

As per the XML schema standard, Include option should be used for including constructs from another message definition file which either has the same target namespace (as the source message definition file) or has no target namespace also known as chameleon namespace. . Follow the following steps to add include statement to a message definition file:

1. Switch to the Broker Application Development perspective. 2. In the Message Definition Editor select the Properties tab. 3. In the Properties Hierarchy right-click on Includes and select Add Include from the

menu. The select Message Definition file to include wizard opens. 4. In the Message Sets pane, select a message definition file you want to include from the

workspace. If the message definition files within your project are not visible in this pane, expand the project hierarchy. To do this click the + next to each icon.

5. Click Finish. The message definition file you selected in step 4 is included within the message definition file you opened before beginning this task.

18

Figure 14: Message Definition Editor -- referencing message definitions

Import

Import option should be used for including constructs from another message definition file, which has different target namespace from the source message definition file. Follow these steps to add import statement to a message definition file:

1. Switch to the Broker Application Development perspective. 2. In the Message Definition Editor, select the Properties tab. 3. In the Properties Hierarchy, right-click on Imports and select Add Import from the

menu. The select Message Definition file to import wizard opens. 4. In the Message Sets pane, select a message definition file you want to import from the

workspace. If the message definition files within your project are not visible in this pane, expand the project hierarchy. To do this click the + next to each icon.

5. Click Finish. The message definition file you selected in step 4 is imported into the schema of the message definition file you opened before beginning this task.

Task list The Task list view is a workbench view and is used to show errors, warnings and bookmarks. Tasks view displays system generated errors, warnings, or information associated with a resource. These are typically produced by builders. For example, if you save a message definition file that contains syntax errors, the errors will automatically be logged in this view. Selecting and double clicking on the task in the task list view will take you directly to object within the message definition that contains the error.

19

To illustrate the task list errors as shown in the following diagram, we created a duplicate global element purchaseOrder in purchaseOrder.mxsd. Selecting the error in the task list view will take you directly to the purchaseOrder element.

Figure 15: Message Definition Editor -- task list entries for errors and warnings

Message definition preferences The message set component contains a set of preferences that can be changed by selecting Window=>Preferences=>Message Set. Changing some of these preferences will change the behavior of how the message set editors work and the type of errors or warnings reported by the message set validator.

20

Figure 16: Message Set Preferences

The “Window=>Preferences=>Message Set=>Validation” preference page lets you change how some of the different message definition constructs are validated. For example, if you change the “Zero Custom Wire Format length count:” preference to severity=ERROR, you get an error for every length count that is set to “0”.

Conclusion This article described the concept of a message set and brief description of the message sets used in the Web order application sample. It described the XML schema based logical model and how you can create multiple physical representations (wire formats) for the logical model. Additionally, it described the message set editor that is used for adding new wire formats and modifying their default values. Finally, the article showed examples of creating a new message definition file by importing from a COBOL copy book and using the spreadsheet style message definition editor to create and maintain message definitions.

21

22

Part 3 of this six-part series will describe how to create the message flows used in the Web order application sample.

References • WebSphere Business Integration Message Broker http://www.ibm.com/software/integration/wbimessagebroker/

• Integrating applications using WebSphere Business Integration Message Broker V5

Part 1: Integration Scenario – Creating a Web Order processing application • XML Schema http://www.w3.org/TR/xmlschema-0/ http://www.w3.org/TR/xmlschema-1/ http://www.w3.org/TR/xmlschema-2/ • XML Schema Infoset Model http://www.eclipse.org/xsd

Trademarks IBM and WebSphere are registered trademarks of IBM Corporation in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml