Adapter Notifications

Overview

This chapter describes how to configure and manage listeners and listener notifications. For a detailed description of Adapter for MSMQ listeners, see Listeners. For a detailed description of the available Adapter for MSMQ listener notifications, see Listener Notifications.

Listeners

Before you Configure New Listeners

About this task

Perform the following tasks before configuring new listeners.

To prepare to configure a new listener

Procedure

  1. Make sure that you have IBM webMethods Integration Server administrator privileges so that you can access Adapter for MSMQ administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
  2. Start Integration Server and Integration Server Administrator, if they are not already running.
  3. Using Integration Server Administrator, make sure that the WmMSMQAdapter package is enabled. To verify the status of the WmMSMQAdapter package, see Enabling Packages.
  4. Using IBM webMethods Designer, create a user-defined package to contain the listener, if you have not already done so. For more information about managing packages, see Package Management for details.
    Note: If you are using Designer, use the Service Development perspective. For more information, see the IBM webMethods Service Development Help for your release.

Configuring New Listeners

About this task

When you configure Adapter for MSMQ listeners, you specify information that Integration Server uses to enable listeners to listen for, and get messages on, a specified queue.

You configure Adapter for MSMQ listeners using Integration Server Administrator.

To configure a new listener

Procedure

  1. In the Adapters menu in Integration Server Administrator navigation area, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, click Configure New Listener.
  4. On the Listeners Type screen, select the type of listener:
    • IBM webMethods Adapter for MSMQ Single-Queue Listener Service
    • IBM webMethods Adapter for MSMQ Multi-Queue Listener Service
  5. On the Configure Listener Type screen, in the IBM webMethods Adapter for MSMQ section, complete the following fields:
    Parameter Description/Action
    Package The package in which to create the listener.

    Create the listener in a user-defined package rather than in the adapter's package. For other important considerations when creating packages for Adapter for MSMQ, see Package Management.

    You must create the package using Designer before you can specify it using this parameter. For general information about creating packages, see the IBM webMethods Service Development Help for your release.

    Folder Name The folder in which to create the listener.
    Listener Name The name of the listener you are configuring.
    Connection Name The connection to associate with the listener.

    From the list of connections, select a connection with a Queue Access Mode set to Inbound.

    Listeners exhibit different behaviors when they are associated with a transactional connection than with non-transactional connection. For more information about the differences, see Listener Transactionality and Behavior.

    Important: If you are using the adapter with Integration Server 8.0 SP1 or earlier, listeners cannot share connections with adapter services. However, listeners can share connections with other listeners.
    Retry Limit The number of times the adapter tries to reconnect if the adapter fails to connect or loses connection with the message queuing computer. Default: 5.
    Retry Backoff Timeout The number of seconds that elapse between each of the retries specified in Retry Limit. Default: 10.
  6. In the Listener Properties section, complete the following fields:
    Parameter Description/Action
    Timeout Time that the message queuing will wait for a message to arrive. Enter this value in milliseconds. Default: 20000
    Reset Before Operation Select one of the following:
    • true - Move the cursor to the front of the queue.
    • false - Do not move the cursor.
  7. Click Save Listener.

Testing Listeners

About this task

In general, you can test listeners to ensure that you have configured them correctly.

To test a listener

Procedure

  1. Configure a listener using Integration Server Administrator. For instructions on how to configure a listener, see Configuring New Listeners.
  2. Configure a listener notification using Designer. For instructions on how to configure a notification, see Configuring Listener Notifications.
  3. Enable the listener notification using Integration Server Administrator. For instructions on how to enable a listener notification, see Enabling Listener Notifications.
  4. Enable the listener using Integration Server Administrator. For instructions on how to enable a listener, see Enabling Listeners.
  5. Make a change in your back-end system to activate the listener. For example, put a message on a queue.

    The listener searches for, filters, and returns messages that match the filter criteria that you specified when you configured the listener on the Configure Listener Type screen. Filtered messages are then sent to the listener notification for further processing.

    For more information on how listeners and listener notifications work at run time, refer to the following sections: Run-Time Processing of Listeners and Notifications and Run-Time Processing of Listeners and Synchronous Listener Notifications.

Viewing Listener Parameters

You can view a listener's parameters from Integration Server Administrator or from Designer. You also can view the notification order of a listener.

Viewing Listener Parameters Using Integration Server Administrator

About this task

Perform the following steps to view listener parameters using Integration Server Administrator.

To view a listener's parameters using Integration Server Administrator

Procedure
  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.

    When using the adapter with Integration Server 8.0 and later, you can sort and filter the list of listeners.

    • To sort information, click the Up and Down arrows at the top of the column you want to sort.
    • To filter the list of listeners:
      1. On the Listeners screen, click Filter Listeners.
      2. Type the criterion by which you want to filter into the Filter criteria box. Filtering is based on the node name, not the notification alias. To locate all notifications containing specific alphanumeric characters, use asterisks (*) as wildcards. For example, if you want to display all notifications containing the string "abc", type *abc* in the Filter criteria box.
      3. Click Submit. The Listeners screen displays the connections that match the filter criteria.
      4. To re-display all listeners, click Show All Listeners.

        You can control the number of listeners that are displayed on this screen. For more information, see Controlling Pagination.

  3. On the Listeners page, click the icon for the listener that you want to see.

    The View Listener screen displays the parameters for the listener. For descriptions of the listener parameters, see Configuring New Listeners.

  4. Click Return to IBM webMethods Adapter for MSMQ Listeners to return to the main listeners screen.

Viewing Listener Parameters Using Designer

About this task

Perform the following steps to view listener parameters using Designer.

To view a listener's parameters using Designer

Procedure
  1. Review the steps in Before you Configure New Listeners.
  2. From Designer, expand the package and folder in which the listener is located.
  3. Double-click the listener you want to view.

    The parameters for the listener appear on the Listener Informationtab. For descriptions of the listener properties, see Configuring New Listeners.

Viewing the Notification Order of a Listener

About this task

Perform the following steps to view the notification order of a listener.

To view the notification order of a listener

Procedure
  1. In the Adapters menu in the navigation area of the administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, click the icon for the listener that you want to view.

    The View Notification Order screen displays the order of the notifications for the listener. To change the notification order for the listener, see Editing the Notification Order.

  4. ClickReturn to IBM webMethods Adapter for MSMQ to return to the Edit Listener screen.

Editing Listeners

About this task

You use Integration Server Administrator to edit the listener in the following situations:

  • If you need to select a newly configured connection, or if you need to change any listener properties, such as filter values, you can update the listener parameters.
  • If you need to change the order of the notifications that are associated with the listener, see Editing the Notification Order.

To edit a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, make sure that the listener is disabled before editing. To disable the listener, see Disabling Listeners.
  4. On the Listeners screen, click the icon for the listener that you want to edit.

    The Edit Listener screen displays the current parameters for the listener. Update the listener's parameters by typing or selecting the values you want to specify.

    For descriptions of the listener parameters, see Configuring New Listeners.

  5. ClickSave Changes to save the listener and return to the Listeners screen.

Editing the Notification Order

About this task

To edit the notification order of a listener

Procedure

  1. In the Adapters menu in the navigation area of the administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, make sure that the listener is disabled before editing. To disable the listener, see Disabling Listeners for details.
  4. On the Listeners screen, click the icon for the listener that you want to edit.
  5. On the Edit Listener screen, click Edit Notification Order.
  6. On the Edit Notification Order screen, use the Up and Down buttons to determine the processing order in which Adapter for MSMQ invokes the notifications.
    Note: For better processing results, arrange your notifications from ascending to descending order starting with the most detailed notifications to the least detailed notifications. For more information on notifications and their filter criteria, see Consideration for Listener Notifications.
  7. Click Save Changes to save the notification order of the listener.
  8. ClickReturn to IBM webMethods Adapter for MSMQ to return to the Edit Listener screen.

Copying Listeners

About this task

You can copy an existing listener to create a new listener with the same or similar properties without having to type or specify all properties for the listener. You copy adapter listeners using Integration Server Administrator.

To copy a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, click the icon for the listener that you want to copy.

    The Copy Listener screen displays the current parameters for the listener that you want to copy. Name the new listener and edit any listener parameters as needed by typing or selecting the values you want to specify.

    For descriptions of the listener parameters, see Configuring New Listeners.

  4. Click Save Changes to save the listener and return to the Listeners screen.

Deleting Listeners

About this task

If you no longer want to use a listener, use the following instructions to delete the listener. You use Integration Server Administrator to delete listeners.

Important: If you delete an Adapter for MSMQ listener, any notifications that are defined to use the listener will no longer work. You cannot change which listener a notification uses after the notification is configured. However, you can change the parameters for an existing listener. For instructions, see Editing Listeners.

To delete a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, make sure that the listener is disabled before deleting it. To disable the listener, see Disabling Listeners for details.
  4. On the Listeners screen, click for the listener you want to delete.

    Integration Server deletes the listener.

Enabling Listeners

About this task

Before you enable a listener, you need to configure one or more notifications to associate with the listener. If no notifications have been configured when you enable the listener, Integration Server Administrator displays the following warning message: "No notifications for listener."

After you have configured notifications, you must enable the listener so that the associated notifications will communicate appropriately with the listener at run time. You enable the listeners using Integration Server Administrator.

The Status column indicates the readiness of the listener. When the status is Succeeded, the listener is ready to be enabled. When the status is Failed,check the following:

  • The queue access mode of the connection. It should be set to inbound.
  • The order in which you disabled the listener and notification. You must disable the listener before disabling the notification.

For more information on configuring listeners and notifications, see the sections Configuring New Listeners and Configuring Listener Notifications.

Important: Before you enable a listener, you must enable the listener notification. For instructions on how to enable a listener notification, see Enabling Listener Notifications.
Note: When you reload a package that contains enabled listeners, the listeners will be enabled automatically when the package reloads. If the package contains disabled listeners, they will remain disabled when the package reloads.

To enable a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. The Listeners screen appears. Select Enabled from the drop-down list in the State field. Integration Server Administrator enables the listener.

    The Enable all suspended link helps you change the state quickly for multiple listeners.

Suspending Listeners

About this task

You can use Integration Server to suspend listeners.

When you suspend a listener, the action may not take effect right away. You may have to wait as long as the time specified in the Timeout parameter for the listener. If one or more messages appear on the queue within that time interval, the adapter may receive and process the first message.

Note: In Adapter for MSMQ, a suspended listener behaves identically to a disabled listener.

To suspend a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. On the Listeners screen, select Suspended from the drop-down list in the State field. Integration Server Administrator suspends the listener.

    The Suspend all enabled link helps you change the state quickly for multiple listeners.

Disabling Listeners

About this task

Listeners must be disabled before you can edit or delete them. You disable listeners using Integration Server Administrator.

When you disable a listener, the action may not take effect right away. You may have to wait as long as the time specified in the Timeout parameter for the listener. If one or more messages appear on the queue within that time interval, the adapter may receive and process the first message.

To disable a listener

Procedure

  1. In the Adapters menu in the navigation area of Integration Server Administrator, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, click Listeners.
  3. The Listeners screen appears. Select Disabled from the drop-down list in the State field. Integration Server Administrator disables the listener.

Listener Notifications

The following sections provide instructions for configuring and managing Adapter for MSMQ listener notifications. Adapter for MSMQ has two types of listener notifications that you can configure:

  • Asynchronous Listener Notifications
  • Synchronous Listener Notifications

For more information on how listener notifications work, see Listener Notifications.

Before You Configure Listener Notifications

About this task

Perform the following tasks before configuring listener notifications.

To prepare to configure a listener notification

Procedure

  1. Install Integration Server and Adapter for MSMQ on the same machine. For details, see Installing, Upgrading, and Uninstalling the Adapter for MSMQ.
  2. Make sure that you have Integration Server administrator privileges so that you can access Adapter for MSMQ administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
  3. Start Integration Server and Integration Server Administrator, if they are not already running.
  4. Using Integration Server Administrator, make sure that the WmMSMQAdapter package is enabled. To verify the status of the WmMSMQAdapter package, see Enabling Packages.
  5. Configure a listener using Integration Server Administrator. For more information on how to configure a new listener, see Configuring New Listeners.
  6. Using Designer, create a user-defined package to contain the listener, if you have not already done so. For more information about managing packages, see Package Management.

Consideration for Listener Notifications

For each listener, configure a default notification that processes all messages that do not pass any notification filter criteria. From Integration Server Administrator, edit the listener's notification order list and place the default notification last. For instructions on how to configure a notification, see Configuring Listener Notifications. For instructions on how to edit the notification order list, see Editing Listeners.

Using Asynchronous and Synchronous Listener Notifications

The following table lists the tasks required to use these types of notifications:

Task   Use this tool...
1 Configure an adapter connection. For details, see Configuring Adapter Connections. Integration Server Administrator
2 Select the appropriate notification template and configure the notification.

For instructions to configure notifications, see Configuring Listener Notifications.

Designer
3 If you plan to use an Integration Server flow or Java service, design it to react to the data changes contained in the notification's publishable document. Configure an Integration Server trigger to use the notification's publishable document.

For instructions on configuring notifications, see the IBM webMethods Service Development Help for your release.

Note: To process the message from the queue, you should create an Integration Server trigger that subscribes to the Integration Server document type that Adapter for MSMQ created with the asynchronous notification. For more information about using triggers, see the Publish-Subscribe Developer’s Guide for your release.
Designer
4 Enable the adapter notifications. For instructions to enable listener notifications, see Enabling Listener Notifications. Integration Server Administrator

Configuring Listener Notifications

Adapter for MSMQ has two types of listener notifications that you can configure:

  • Asynchronous Listener Notifications
  • Synchronous Listener Notifications

For a description of the asynchronous and synchronous listener notifications, see Listener Notifications. You configure listener notifications using Designer.

Configuring Asynchronous Listener Notifications

About this task

Perform the following tasks to configure asynchronous listener notifications.

To configure an MSMQ asynchronous listener notification

Procedure
  1. Review the steps in Before You Configure Listener Notifications.
  2. Start Designer.
  3. Using Designer, perform the following:
    1. Right-click the package in which the notification should be contained and select New > Adapter Notification.
    2. Select the parent namespace and type a name for the adapter notification.
    3. Click Next.
  4. Select IBM webMethods Adapter for MSMQ as the adapter type and click Next.
  5. Select Asynchronous Listener Notification from the template and clickNext.
  6. Select the appropriate Notification Listener Nameand click Next.
  7. Select a package and folder to contain the notification, type a unique name for the notification, and click Next.
  8. Click Finish.
  9. Designer creates an asynchronous listener notification and an asynchronous publishable document type, and the editor for the adapter notification appears.
    1. You can select the Adapter Settings tab at any time to confirm listener notification properties such as the Adapter Name, Adapter Listener Name, and Adapter Notification Template as necessary.
    2. In the Publish Document section, you can specify how you want the notification document to be published:
      • To publish documents to Broker, select IBM webMethods Broker /Local. This is the default option.
      • To publish documents to a JMS provider, select JMS Provider, and provide values for the following input fields:
        Field Description/Action
        Connection alias name The name of the JMS connection alias configured on Integration Server.
        Destination name The name of the destination from which you want the JMS trigger to receive messages.
        Destination type Whether the destination is a Queue (default) or a Topic.
  10. Select theFilter tab to specify which property values should match the arriving message to run the notification.
    1. From the drop-down menu, select one of the following Message Filtering Modes:
      • MATCH_ONE - Any one of the selected properties can be used to identify the message.
      • MATCH_ALL - All selected properties will be used to identify the message.
        Note: If none of the properties are selected, all messages will pass the filter criteria.
    2. Select the property fields and enter the values for the properties. Use the following icons to manage the rows in theProperty column:
      • To define new property fields, select the icon (or the icon).
      • To change the order of the property fields to ensure that the parameters are parsed in the correct order, use the or icons.
      • To delete a property field, use the icon.
      You can add the following property fields to the Property column.
      Property Description
      MessageId Identifies the message using a hex string.
      CorrelationId Identifies the message using a hex string correlation identifier. For example, {F944A0B1-1DA0-4A93-A266-E54ACDD55342}\30775.
      Delivery Specifies how Message Queuing delivers the message. Valid values are:
      • 1 - indicates that along its route, the message is stored locally on disk until it is forwarded to the next computer.
      • 0 - indicates that along its route, the message stays in volatile memory until it is received.
      Priority Specifies the message priority. The value is between 0 - 7. The lower number indicates lower priority. Default: 3.
      Note: Message Queuing automatically sets the priority level of the transactional messages to 0, which indicates that the priority is ignored by the transaction.
      AppSpecific Specifies application-generated single integer values.
  11. Select the Output Message Property tab to identify the message property fields that will be generated in the notification publishable document.

    You can add the following property fields:

    Property Property Type Description
    Ack java.lang.Integer Specifies the type of acknowledgment messages that Message Queuing will post in the administration queue when acknowledgments are requested.
    AdminQueuePathName java.lang.String Specifies the queue path name used for Message Queuing-generated acknowledgment messages.
    AdminQueueFormatName java.lang.String Specifies the queue format name used for Message Queuing-generated acknowledgment messages.
    AppSpecific java.lang.Integer Specifies application-generated single integer values.
    ArrivedTime java.lang.String Specifies the time when the message arrives in the queue.
    CorrelationId java.lang.String Identifies the message using a hex string correlation identifier. For example, {F944A0B1-1DA0-4A93-A266-E54ACDD55342}\30775.
    CorrelationIdByteArray byte array Identifies the message using a 20-byte correlation identifier.
    Delivery java.lang.Integer Specifies how Message Queuing delivers the message. Valid values are:
    • 1 - indicates that along its route, the message is stored locally on disk until it is forwarded to the next computer.
    • 0 - indicates that along its route, the message stays in volatile memory until it is received.
    DestinationQueuePathName java.lang.String Specifies the destination queue path name of the message
    DestinationQueueFormatName java.lang.String Specifies the destination queue format name of the message.
    MessageId java.lang.String Identifies the message using a hex string.
    MessageIdByteArray byte array Identifies the message using an MSMQ-generated 20-byte message identifier.
    IsAuthenticated java.lang.Integer Indicates whether the message was authenticated at the request of the sending application. Valid values are:
    • 1 - the message is authenticated.
    • 0 - the message is not authenticated.
    IsFirstInTransaction java.lang.Integer Indicates whether the message was the first message sent in its transaction. Valid values are:
    • 1 - the message is first.
    • 0 - the message is not first.
    IsLastInTransaction java.lang.Integer Indicates whether the message was the last message sent in its transaction. Valid values are:
    • 1 - the message is last.
    • 0 - the message is not last.
    Label java.lang.String Provides a description of the message.
    Journal java.lang.Integer Specifies whether Message Queuing stores copies of the message as it is routed to the destination queue. Valid values are:
    • 0 - the journal is disabled.
    • 1 - the message is stored in the applicable dead-letter queue on failure.
    • 2 - a copy of the message is stored in the computer journal if the message was successfully delivered to the next computer.
    MaxTimeToReachQueue java.lang.Integer Specifies the time limit (in seconds) for a message to reach the queue.
    MaxTimeToReceive java.lang.Integer Specifies the time limit (in seconds) for the message to be retrieved from the target queue.
    MsgClass java.lang.Integer Indicates the message type.
    Priority java.lang.Integer Specifies the message priority. The value is between 0 - 7. The lower number indicates lower priority. Default: 3.
    Note: Message Queuing automatically sets the priority level of the transactional messages to 0, which indicates that the priority is ignored by the transaction.
    SendTime java.lang.String Indicates when the message is sent.
    SourceMachineGuid java.lang.String Indicates the GUID of the computer that sent the message.
  12. Select the Permissions tab to manage the access control list (ACL) information. Use the drop-down menu to select each of the ACL types. For general information about assigning and managing ACLs, see the IBM webMethods Service Development Help for your release.
  13. From the File menu, select Save.

Configuring Synchronous Listener Notifications

About this task

Perform the following tasks to configure synchronous listener notifications.

To configure an MSMQ synchronous listener notification

Procedure
  1. Review the steps in Before You Configure Listener Notifications.
  2. Start Designer.
  3. Using Designer, perform the following:
    1. Right-click the package in which the notification should be contained and select New > Adapter Notification.
    2. Select the parent namespace and type a name for the adapter notification.
    3. Click Next.
  4. Select IBM webMethods Adapter for MSMQ as the adapter type and click Next.
  5. Select Synchronous Listener Notification from the template and clickNext.
  6. Select the appropriate Notification Listener Nameand click Next.
  7. Select the appropriate Service Node and click Next.
  8. Select a package and folder to contain the notification, type a unique name for the notification, and click Next.
  9. Click Finish.

    The Adapter Notification template creates the following items:

    • A Synchronous Listener Notification
    • Two Synchronous Document Types:
      • Synchronous Reply Document Type
      • Synchronous Request Document Type
      Note: You cannot edit any fields or properties on the Publications Properties tab for the Synchronous Request and Reply Document Types. Integration Server does not publish these document types.
  10. Select the Adapter Settings tab, to view the adapter properties and to select the appropriate service name for the synchronous notification.
    1. The following fields in the Adapter Properties section are read-only:
      Adapter Properties Description
      Adapter Name The name of the adapter.
      Adapter Listener Name The name of the adapter listener that you selected when you configured the synchronous notification.
      Adapter Notification Template The name of the adapter notification template that you selected when you configured the synchronous notification.
    2. Specify one of the following modes in the Execution Mode section:
      • To invoke a flow service directly, select Service Invoke and specify the following field:
        Property Description
        Service Name The name of the service, which you selected when you initially configured the adapter listener notification, appears in the Service Name field.

        Select a different service by clicking the icon to the right of the Service Name field.

        Important: Before you select a different service, make sure that you have disabled the notification. When the notification is enabled, then the new service is utilized. For more information on enabling and disabling listeners, see Enabling Listeners and Disabling Listeners.
      • To publish documents locally or to a Broker and wait for a reply, select Publish and Wait and specify the following fields:
        Properties Description
        Local Select true to publish documents locally (to this Integration Server only) or false to publish to the Broker connected to this Integration Server.
        Note: If no Broker is configured for Integration Server, documents will be published locally.
        Wait Time Specify the number of milliseconds to wait for a reply. The default is -1, which means to wait indefinitely.
  11. Select theFilter tab to specify which property values should match the arriving message to run the notification.
    1. From the drop-down menu, select one of the following Message Filtering Modes:
      • MATCH_ONE - Any one of the selected properties can be used to identify the message.
      • MATCH_ALL - All selected properties will be used to identify the message.
        Note: If none of the properties are selected, all messages will pass the filter criteria.
    2. Select the property fields and enter the values for the properties. Use the following icons to manage the rows in theProperty column:
      • To define a new property, select the icon (or the icon).
      • To change the order of the properties to ensure that the parameters are parsed in the correct order, use the or icons.
      • To delete a property, use the icon.
      You can add the following property fields:
      Property Description
      MessageId Identifies the message using a hex string.
      CorrelationId Identifies the message using a hex string correlation identifier. For example, {F944A0B1-1DA0-4A93-A266-E54ACDD55342}\30775.
      Delivery Specifies how Message Queuing delivers the message. Valid values are:
      • 1 - indicates that along its route, the message is stored locally on disk until it is forwarded to the next computer.
      • 0 - indicates that along its route, the message stays in volatile memory until it is received.
      Priority Specifies the message priority. The value is between 0 - 7. The lower number indicates lower priority. Default: 3.
      Note: Message Queuing automatically sets the priority level of the transactional messages to 0, which indicates that the priority is ignored by the transaction.
      AppSpecific Specifies application-generated single integer values.
  12. Select the Output Message Property tab to identify the message property fields that will be generated in the notification request document.

    You can add the following property fields:

    Property Property Type Description
    Ack java.lang.Integer Specifies the type of acknowledgment messages that Message Queuing will post in administration queue when acknowledgments are requested.
    AdminQueuePathName java.lang.String Specifies the queue path name used for Message Queuing-generated acknowledgment messages.
    AdminQueueFormatName java.lang.String Specifies the queue format name used for Message Queuing-generated acknowledgment messages.
    AppSpecific java.lang.Integer Specifies application-generated single integer values.
    ArrivedTime java.lang.String Specifies the time when the message arrives in the queue.
    CorrelationId java.lang.String Identifies the message using a hex string correlation identifier. For example, {F944A0B1-1DA0-4A93-A266-E54ACDD55342}\30775.
    CorrelationIdByteArray byte array Identifies the message using a 20-bytes correlation identifier.
    Delivery java.lang.Integer Specifies how Message Queuing delivers the message. Valid values are:
    • 1 - indicates that along its route, the message is stored locally on disk until it is forwarded to the next computer.
    • 0 - indicates that along its route, the message stays in volatile memory until it is received.
    DestinationQueuePathName java.lang.String Specifies the destination queue path name of the message
    DestinationQueueFormatName java.lang.String Specifies the destination queue format name of the message.
    MessageId java.lang.String Identifies the message using hex string.
    MessageIdByteArray byte array Identifies the message using an MSMQ-generated 20-byte message identifier.
    IsAuthenticated java.lang.Integer Indicates whether the message was authenticated at the request of the sending application. Valid values are:
    • 1 - the message is authenticated.
    • 0 - the message is not authenticated.
    IsFirstInTransaction java.lang.Integer Indicates whether the message was the first message sent in its transaction. Valid values are:
    • 1 - the message is first.
    • 0 - the message is not first.
    IsLastInTransaction java.lang.Integer Indicates whether the message was the last message sent in its transaction. Valid values are:
    • 1 - the message is last.
    • 0 - the message is not last.
    Label java.lang.String Provides a description of the message.
    Journal java.lang.Integer Specifies whether Message Queuing stores copies of the message as it is routed to the destination queue. Valid values are:
    • 0 - the journal is disabled.
    • 1 - the message is stored in the applicable dead-letter queue on failure.
    • 2 - a copy of the message is stored in the computer journal if the message was successfully delivered to the next computer.
    MaxTimeToReachQueue java.lang.Integer Specifies the time limit (in seconds) for a message to reach the queue.
    MaxTimeToReceive java.lang.Integer Specifies the time limit (in seconds) for the message to be retrieved from the target queue.
    MsgClass java.lang.Integer Indicates the message type.
    Priority java.lang.Integer Specifies the message priority. The value is between 0 - 7. The lower number indicates lower priority. Default: 3.
    Note: Message Queuing automatically sets the priority level of the transactional messages to 0, which indicates that the priority is ignored by the transaction.
    SendTime java.lang.String Indicates when the message is sent.
    SourceMachineGuid java.lang.String The property provides the GUID of the computer that sent the message.
  13. Select the Permissions tab to manage the access control list (ACL) information. Use the drop-down menu to select each of the ACL types. For general information about assigning and managing ACLs, see the IBM webMethods Service Development Help for your release.
  14. From the Filemenu, select Save.

Editing Synchronous Listener Notification Services

About this task

The listener notification service is specified during the initial configuration of the synchronous listener notification. Afterwards you may need to change the service that is invoked. To change the notification service, complete the following steps.

Important: Before you select a different service, make sure that you have disabled the notification. When the notification is enabled, the new service is utilized. To disable the notification, see Disabling Listener Notifications.

To edit the notification service

Procedure
  1. From Designer, in the adapter notification service editor, select the Adapter Settings tab.
  2. Click the Browse button next to Service Name. The Select Menu displays.
  3. Navigate and select the new service.
  4. Click OK.
  5. From the File menu, select Save.

Behavior of Listener Notifications

Adapter for MSMQ handles messages depending on how you have configured listeners and listener notifications in your system. For example, messages behave differently when the following combinations are set up in your Adapter for MSMQ:

  • Transactional or non-transactional listeners

    The transactionality of a listener depends on the transactionality of the connection. For example, when you associate a non-transactional connection with a listener, the listener is non-transactional.

  • Transactional or non-transactional asynchronous notifications

    The transactionality of an asynchronous notification depends on the transactionality of a listener. For example, when you associate a non-transactional listener with an asynchronous notification, the asynchronous notification is non-transactional.

  • Transactional or non-transactional synchronous notifications

    The transactionality of a synchronous notification depends on the transactionality of a listener. For example, when you associate a non-transactional listener with a synchronous notification, the synchronous notification is non-transactional.

Testing Listener Notifications

About this task

You can test listener notifications to ensure that you have configured them correctly.

To test listener notifications

Procedure

  1. Configure a listener using Integration Server Administrator. For instructions to configure a listener, see Configuring New Listeners.
  2. Configure a listener notification using Designer. For instructions to configure a notification, see Configuring Listener Notifications.
  3. Enable the listener notification using Integration Server Administrator. For instructions to enable a listener notification, see Enabling Listener Notifications.
  4. Enable the listener using Integration Server Administrator. For instructions to enable a listener, see Enabling Listeners. Make a change in your back-end system to activate the listener. For example, put a message on a queue.

    The listener searches for, filters, and returns messages that match the filter criteria that you specified when you configured the listener on the Configure Listener Type screen. Filtered messages then are sent to the listener notification for further processing.

    For more information on how listeners and listener notifications work at run time, refer to the following sections: Run-Time Processing of Listeners and Notifications and Run-Time Processing of Listeners and Synchronous Listener Notifications.

Testing Publishable Document Types

You can test a publishable document type that is associated with an asynchronous notification running it in Designer. When you test a publishable document type, you provide input values that the Designer uses to create an instance of the publishable document type. You also specify a publishing method (such as publish, publish and wait, deliver, or deliver and wait). Designer then publishes a document and displays the results of the publish in the Results dialog box. Testing a publishable document type provides a way for you to publish a document without building a service that does the actual publishing. If you select a publication action where you wait for a reply document, you can verify whether reply documents are received.

Note: Prior to running the PublishDocument, you need to make sure that you uncheck the Field must exist at run-time field on the msgBody property. To access this field, right-click msgBody, select Properties, and then select the Constraints tab. When you test a publishable document type, Integration Server actually publishes the document locally or to the Broker (whichever is specified).

For instructions to test a publishable document type, see the Publish-Subscribe Developer’s Guidefor your release. Also, for a complete description of the envelope parameters located in the WmPublic folder, see the IBM webMethods Integration Server Built-In Services Referencefor your release. The envelope parameters define the sender's address, the time the document was sent, password and certificate information, and other useful information for routing and control.

Viewing Listener Notifications

About this task

You use the Designer to view listener notifications.

To view a listener notification

Procedure

  1. Review the steps in Before You Configure Listener Notifications.
  2. In Designer, expand the package and folder that contain the listener notification you want to view.
  3. Select the listener notification that you want to view.

    Designer displays the configured listener notification in the adapter's Adapter Notification Editor.

Editing Listener Notifications

About this task

You use Designer to edit both synchronous and asynchronous listener notifications. You also use Designer to edit the publishable document type associated with the asynchronous listener notifications. However, you cannot edit the request and reply document types that are associated with synchronous listener notifications.

Editing a Listener Notification

About this task

Perform the following tasks to edit a listener notification.

To edit a listener notification

Procedure
  1. In Designer, expand the package and folder that contain the listener notification you want to edit.
  2. Select the listener notification you want to edit.

    Designer displays the configured listener notification in the adapter's Adapter Notification Editor.

  3. Do one of the following:
    • If you have the VCS Integration feature enabled, right-click the notification and select Check Out.
    • If you do not have the VCS Integration feature enabled, right-click the notification and select Lock for Edit.
    • If you are using the local service development feature, from the Team menu in Designer, select the appropriate option to check out the notification. The options available in the Team menu depend on the VCS client that you use.
  4. Modify the values for the listener notification's parameters as needed. For detailed descriptions of the notification's parameters, see Configuring Listener Notifications for the specific type of listener notification that you want to edit.
    Note: Because listener notifications inherently depend on listeners, you cannot change a listener for a listener notification after you configure it.
  5. After you have completed your modifications, save the notification and do one of the following:
    • If you have the VCS Integration feature enabled, right-click the notification and select Check In. Enter a check-in comment and click OK.
    • If you do not have the VCS Integration feature enabled, right-click the notification and select Unlock.
    • If you are using the local service development feature, from the Team menu in Designer, select the appropriate option to check in the notification. The options available in the Team menu depend on the VCS client that you use.

Editing an Asynchronous Publishable Document Type

About this task

Perform the following tasks to edit an asynchronous publishable document type.

To edit an asynchronous publishable document type

Procedure
  1. In Designer, expand the package and folder that contain the publishable document type that you want to edit.
  2. Select the asynchronous publishable document type that you want to edit.

    Designer displays the configured asynchronous publishable document type in the adapter's Adapter Listener Editor.

  3. Select the Publication Properties tab, and modify the available values for the document type's parameters as needed. For detailed descriptions of the asynchronous document type's parameters, see Configuring Asynchronous Listener Notifications.

Deleting Listener Notifications

About this task

If you no longer want to use a particular Adapter for MSMQ listener notification, you can delete it by following the instructions in this section. You delete listener notifications, both synchronous and asynchronous, using Designer.

Important: If you delete a synchronous listener notification, the associated request and reply document types are deleted automatically. If you delete an asynchronous listener notification, the associated publishable document type is deleted automatically. You cannot solely delete the document types associated with the synchronous and asynchronous listener notifications.

To delete a listener notification

Procedure

  1. In Designer, expand the package and folder that contain the listener notification you want to delete.
  2. Right-click the listener notification and click Delete.

Enabling Listener Notifications

About this task

After you configure a listener notification, you need to enable it using Integration Server Administrator.

To enable a listener notification

Procedure

  1. In the Adapters menu in Integration Server Administrator navigation area, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, select Listener Notifications.
  3. On the Listener Notifications screen, click No in the Enabled column for the listener notification you want to enable.

    Integration Server Administrator enables the listener notification and displays a and Yesin theEnabled column.

Disabling Listener Notifications

About this task

You disable listener notifications using Integration Server Administrator.

Important: Before you disable a listener notification, you must disable the associated listener. For instructions on how to disable a listener, see Disabling Listeners.

To disable a listener notification

Procedure

  1. In the Adapters menu in Integration Server Administrator navigation area, click IBM webMethods Adapter for MSMQ.
  2. In the IBM webMethods Adapter for MSMQ menu, select Listener Notifications.
  3. On the Listener Notifications screen, click Yesin the Enabled column for the listener notification you want to disable.

    The listener notification becomes disabled and Nodisplays in theEnabled column.