Creating a message broker project

Once you have created the business object definitions the connector is to support, you must deploy them into the message broker workspace (for WebSphere Business Integration Message Broker ) or deploy them to the message broker (for WebSphere MQ Integrator or WebSphere MQ Integrator Broker .) You do this using the System Manager . System Manager is installed with the Adapter Framework and provides a graphical user interface from which to configure and administer adapters. (For more information about System Manager, refer to the Appendix E, System Manager and the Eclipse Workbench.)

Note:
The connector must be installed before you can deploy the project to the message broker. Refer to the WebSphere Business Integration Adapters Installation Guide for installation instructions.

To start System Manager, from the Windows Start menu select IBM WebSphere Business Integration Adapters > Tools > System Manager. Make sure you are viewing the System Manager perspective. The first step you should complete before creating a new project is to specify the importer paths.

Specifying importer and workspace paths

You must specify the paths for the broker importer and message broker workspace directory before you deploy a project to a message broker if they are not in the same workspace.

Note:
If you are deploying business objects to WebSphere Business Integration Message Broker, and the System Manager and Message Broker Toolkit are in the same plugin directory you do not have to perform this step. During deployment, the specified project will be created in the current System Manager workspace.
Tip

After deployment, the Broker Application Development perspective in the System Manager workbench will display an entry for the destination message set project. If plugins for both System Manager and the Message Broker Toolkit are launched when you start the workbench, then they are in the same workspace. If you can see the Broker Application Development perspective in the same workbench as System Manager, then the Message Broker Toolkit plugins were also launched.

If the broker importer and message broker workspace are in different directories, specify their paths as follows:
  1. From System Manager select Window > Preferences > System Manager Preferences >Broker Preferences. The following window appears:
    Screen capture showing Broker Preferences window. Fill in as instructed in text.
  2. Enter (or click Browse to locate) the pathnames as follows:

    For WebSphere MQ Integrator Broker or WebSphere MQ Integrator, enter the integrator importer path (under "Integrator Broker Settings"). The importer is called mqsilmpXMLSchema.exe and should be found in the bin directory of your broker installation.

    For WebSphere Business Integration Message Broker, enter the message broker importer path and the message broker workspace directory (under "Message Broker Settings"). The importer is called mqsicreatemsgdefs.exe and should be found in the eclipse directory of your broker installation. Make sure to select the message broker workspace, not the System Manager workspace. The default path for the message broker workspace is eclipse\workspace. (The message broker workspace is the workspace used to store the message set and message flow projects, and any other projects of WebSphere Business Integration Message Broker tooling.)

    Note:
    Pathnames entered should be absolute.

Creating a new user project

To create a new user project, follow these steps:

  1. From the User Projects menu, select Message broker Projects and then New Message broker project as in the following illustration:
    Screen capture of System Manager showing Broker Project and subitem New Broker project selected.
  2. A New User Project window will be displayed. Enter the name of the project. For example:
    Screen capture of System Manager New User Project window.
  3. In the Available Integration Component Libraries window you will see a list of the integration component libraries that have been detected. (Note: A path to the libraries must be entered when you install System Manager). Select the plus signs (+) to expand the checkboxes in the Available Integration Component Libraries window and select the business object definitions and connectors you wish to include in this project.
    Note:
    Selecting the checkbox beside "Business Objects" (as in the example) will select all available business object definitions. Selecting the checkbox beside "Connectors" (as in the example) will select all available connectors.
  4. Click Finish. The name of the new project will appear in the Broker Projects list in System Manager.
  5. In the User Projects panel, expand the name of the new project and the "Business Objects" and "Connectors" items that appear and you will see the names of the Business Objects and Connectors that you selected.

The remaining steps in the deployment process differ depending upon which message broker you are using as an integration broker. In the next step you will right-click on the new project name and choose one of two types of deployment, as follows:

If you are using... Select... Refer to...
WebSphere Business Integration Message Broker Deploy to message broker workspace "Deploying to a message broker workspace"
WebSphere MQ Integrator Deploy to integrator broker "Deploying to an integrator broker"
WebSphere MQ Integrator Broker

Deploying to a message broker workspace

To deploy the project to a message broker workspace (for WebSphere Business Integration Message Broker used as the integration broker), do the following from System Manager:

  1. Right-click on the name of the new project in the User Projects panel, then select "Deploy to message broker workspace" as shown in the following illustration:
    Screen capture showing selection of "Deploy to message broker workspace"
    The following window appears, showing the available business objects:
    Screen capture showing "Deploy to Message broker workspace" window
  2. Choose the desired business objects in the list (or "Select all business objects" or "Show only Top level Business objects").
  3. Click Next. The following window appears:
    Screen capture showing Select the Parameters window
  4. Enter a name for the Message Set project (required) and any other parameters (optional). The parameters are described in more detail below:

    Message set project name . Any text string designating the name of this project. This name will appear in the System Manager window when deployment is complete.

    Base message set project and base message set. If you enter names of an existing base message set project and base message set, then the contents of the base message set will be used as the basis of the new destination project. All the message set definitions in the base project will be copied to the new destination project. In addition, the destination project will also include any business objects you selected from the previous window during this deployment. You can view the names of existing message set projects and base message sets from the Broker Application Development perspective of Message Broker Tooling.

    Note:
    You must enter both a base message set project and a base message set; if only one of these parameters is specified, it will be ignored, and only those business objects selected during this deployment will be included in the project.

    Replace existing project with the same name. This option is applicable if the name entered in the Enter message set project name field is identical to the name of an existing project. If so, selecting this option replaces an existing project's content with content based on your selections during this deployment (only the name remains the same) . If this option is not checked and the specified project name matches that of an existing project, then the project retains whatever business objects it already contained and those selected during this deployment will be added. All existing business objects with the same names will be overwritten. If this option is checked but the project name does not match an existing project, this option is ignored and a new project is created.

    Namespace aware and xml namespace format. By default, XML namespace format is set to short. It is important to select the correct combination of choices for Namespace aware and XML namespace format, or your deployment might fail. Refer to "Choosing XML Namespace length" for information on whether to select long or short for this parameter.

    Deploy in verbose mode . Selecting this option will cause more details of the deployment process to be displayed or logged during deployment.

  5. Click Finish. If the project deploys successfully, a window will display a message indicating successful deployment. In addition, The results of the deployment will be recorded in the default log file mqsicreatemsgdefs.report.txt,located in the importer directory (default directory eclipse ). Also refer to the console panel of System Manager; it will display which business objects have successfully deployed.
    Note:
    The Message Broker Toolkit must closed when you click Finish for deployment to succeed. If the Toolkit was open at this time, you will receive a message stating that deployment of some or all of the business objects and message sets failed. You must redeploy from the beginning of the process, making sure that the Toolkit is closed.

Deploying to an integrator broker

To deploy the project to an integrator broker (for WebSphere MQ Integrator or WebSphere MQ Integrator Broker used as the integration broker), do the following from System Manager:

  1. Right-click on the name of the new project in the User Projects panel, then select "Deploy to integrator broker" as shown in the following illustration:
    Screen capture showing "Deploy to integrator broker" window
    The following window appears, showing the available business objects:
    Screen capture showing "Deploy to Integrator Broker" window
  2. Choose the desired business objects in the list (or"Select all business objects" or "Show only Top level Business objects".
  3. Click Next. The Parameter Selection window appears. This window allows you to change WebSphere MQ Integrator values and to select the XML namespace format for the connector. For example:
    Screen capture showing Parameter Selection screen for WebSphere MQ Integrator values.
  4. Enter the Password (DB_PW property) and any other values to change from the defaults. (Values entered from any previous use of this window will have been saved and will be presented as the defaults.) Note that by default, XML namespace format is set to short. It is important to select the correct combination of choices for Namespace aware and XML namespace format, or your deployment might fail. Refer to Choosing XML Namespace length for information on whether to select long or short for this parameter.
  5. Click Finish. If deployment is successful, a window will appear with a message indicating sucessful deployment. Also refer to the console panel of System Manager; it will display which business objects have successfully deployed.

Choosing XML Namespace length

When you deploy your project to a message broker, you have the option of selectinglong or short XMLNameSpace format. The default is short. XMLNameSpaceFormat is a standard configuration connection property for adapters. The choice you make within System Manager overrides whatever might already exist in the adapter's configuration file. If you are deploying to WebSphere Business Integration Message Broker, the Select the parameters window allows you to specify that the project is namespace-aware. If the project is namespace-aware, either short or long formats are allowed. If the project is not namespace-aware, then long must be used. Selecting short with a project that is not namespace-aware will cause deployment to fail.

Note:
IBM recommends that any new projects be set to namespace-aware mode for ongoing compatibility with industry standards. IBM recommends setting XMLNameSpace format to short, if possible, for better performance.
If you are deploying to WebSphere MQ Integrator or WebSphere MQ Integrator Broker, then long or short are allowed. However, if short is selected, then the RFH2messagedomain property of the connector must be set to xml. If RFH2messagedomain is set to mrm, only XML messages in long namespace format can be processed.
Note:
WebSphere MQ Integrator and WebSphere MQ Integrator Broker do not support namespaces. Therefore you cannot specify namespace-aware for projects deployed to these brokers.
Table 12 shows the XMLNameSpace format alternatives available:

Table 12. XMLNameSpace format alternatives

Message Broker Namespace aware?

Yes No
WebSphere Business Integration Message Broker long or short long
WebSphere MQ Integrator or WebSphere MQ Integrator Broker N/A long or short (for short, RFH2messagedomain must be xml)

Copyright IBM Corp. 1997, 2004