Adapter Notifications

Overview

MessageListener notifications monitor a JMS destination and notify Integration Server when a message arrives on the JMS destination. This section provides instructions for configuring and managing MessageListener notifications.

Before Configuring or Managing Notifications

About this task

Perform the following tasks before configuring or managing adapter notifications.

To prepare to configure or manage MessageListener notifications

Procedure

Start your Integration Server and Integration Server Administrator, if they are not already running.
Make sure you have Integration Server Administrator and IBM webMethods Designer privileges so that you can access the Integration Server's administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
If you plan to use the Only Once notification feature, see Using the Exactly Once Notification Feature for details.
Using Integration Server Administrator, make sure the WmJMSAdapter package is enabled. See Enabling Packages for instructions.
Using Integration Server Administrator, configure an adapter connection to use with the notification. See Configuring Adapter for JMS Connections for instructions.

Note: Integration Server solves this limitation by providing a built-in service that you can use at design time to change the connection associated with a polling notification. For more information, see Changing the Connection for an Adapter Service or Notification at Design Time.
Start Designer if it is not already running.
Using Designer, create a user-defined package to contain the notification, if you have not already done so. When you configure notifications, you should always define them in user-defined packages rather than in the WmJMSAdapter package. For more information about managing packages for the adapter, see Package Management.
You must schedule a notification and then enable it before you can use the notification. See Managing MessageListener Notifications for instructions.

Configuring MessageListener Notifications

About this task

When you configure MessageListener notifications, you specify information that Integration Server uses to read data from a JMS Destination and publish a notification document. For more information about notifications, see Adapter Notifications.

To configure a MessageListener notification

Procedure

Review the steps in Before Configuring or Managing Notifications.
Start Designer.
Right-click the package in which the notification should be contained and select New > Adapter Notification.
Select the parent namespace and type a name for the adapter notification. Click Next.
Select IBM webMethods Adapter for JMS as the adapter type and click Next.
Select the MessageNotification template and click Next.
Select the appropriate Adapter Connection Name and click Next.
The name of the publishable document associated with this notification displays. Click Finish.

For more information about adapter notifications and publishable documents, see Adapter Notifications. For more details about Integration Server publishable documents, see the Publish-Subscribe Developer’s Guide for your release.
Designer creates the notification, and the editor for the adapter notification appears. You can select the Adapter Settings tab at any time to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Notification Template, as necessary.

Select the Notification tab and provide values for the following fields:

Parameter	Description
Destination Type	This property is populated based on the Adapter for JMS connection associated with this notification. For connections associated with queues, the value will be QUEUE. For connections associated with topics, the value will be TOPIC.
Destination JNDI Name	The JNDI name of the queue or topic you want the notification to monitor for messages. Provide a Queue Name if the Destination Type is QUEUE. Provide a Topic Name if the Destination Type is TOPIC.
Message Selector	The SQL-92 compliant message selector expression used for filtering messages.
Connection Client ID	This parameter is only used if the Run as True Listener option is selected. This field only applies to topics.The unique connection ID to use when connecting to a JMS provider topic.If the connection factory has a default Client ID, the notification will use the default, not the value specified in this parameter. Note: Do not change this field after you have saved the notification; doing so could potentially cause orphaned durable subscriptions on the JMS destination. Note: If you need to use a Client ID for the notifications, it is better to specify it along with the other notification parameters using Designer, and not while creating the connection factory or the Adapter for JMS connections. When the Client ID is specified in the connection factory or JMS connections, only one connection can be created through this connection factory or connection. This limits the Adapter for JMS from leveraging the connection pool.
Durable Subscription Name	The unique subscription name to use when creating durable subscriptions. If this field is left blank, the adapter will use the name of the notification for the value of this field. Note: Do not change this field after you have saved the notification because doing so could potentially cause orphaned durable subscriptions on the JMS destination.
Maximum Messages	This field only applies when the notification does not have the Run as True Listener option enabled. The value of this field specifies the maximum number of messages to retrieve every time the notification polls the JMS destination for messages.By default the value is -1, which indicates that the notification retrieves all available messages from the queue or topic every time it polls the JMS destination. Note: Do not set the maximum messages to zero because the notification will not retrieve any messages.
Receive Timeout	The notification will wait for as many milliseconds as are indicated in this field. Provide a value as follows: 1 or greater: The number of milliseconds the notification will wait. 0: The notification will not wait if there are no messages on the queue or topic. -1:The notification will wait indefinitely to receive messages. This is the default.
Run as True Listener	If this option is enabled, the notification will not poll for messages. Instead, it listens to the JMS destination and publishes the associated notification as soon as a message arrives in the JMS destination. If you disable the associated connection, this notification will continue to run (see Disabling Adapter Connections).
Exactly Once Notification	If this option is enabled, Integration Server ignores duplicate messages from this notification if published. Note: This option applies only if you are publishing a document with the notification.
Use Durable Subscription	If this option is enabled, the notification creates durable subscriptions for the topic.
notificationField Names and notificationField Types	This table shows the structure of the publishable document type associated with the notification.
Notification Service	If you want the notification to directly invoke a service rather than publishing a document to Integration Server (which you could then use with an Integration Server trigger to invoke a service), provide the name of a service in this field.If you provide a service name here, the input signature for the service must be constructed the same way as an input signature for a service that is invoked by a trigger. However, the service cannot use any of the _env fields in the signature. See the Publish-Subscribe Developer’s Guide. Important: This option provides the only way to use notifications for JMS providers whose implementation of the JMS message interface 'javax.jms.Message' does not implement the Serializable interface. This option must be used by the Web Application Server JMS providers.

For information about using the Permissions tab to assign an access control list (ACL) to an element, see the IBM webMethods Service Development Help for your release.
Select File > Save.
By default a notification is disabled when it is configured. You must schedule and enable the notification using Integration Server Administrator before you can use it. See Managing MessageListener Notifications for details.

Managing MessageListener Notifications

About this task

You must schedule a MessageListener notification and then enable it before you can use the notification to monitor JMS destinations for messages. Use Integration Server Administrator along with the following procedures to do so.

Note: You cannot enable a notification if the adapter connection that the notification is using is disabled.

Note: You must have IBM webMethods Integration Server privileges to access the Integration Server Administrator's administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.

To manage MessageListener notifications

Procedure

Review the steps in Before Configuring or Managing Notifications.
Start Integration Server Administrator.
From the Adapters menu in the navigation area of Integration Server Administrator, select IBM webMethods Adapter for JMS.
From the navigation area, select Polling Notifications. All configured Adapter for JMS notifications are displayed.

From the IBM webMethods Adapter for JMS Polling Notifications table, use the fields in the following table to manage each adapter notification:

Field	Description/Action
Notification Name	The name of the notification.
Package Name	The name of the package for the notification.
State	You must schedule a polling notification before you can enable it. To schedule a polling notification, use the icon described in these procedures. After doing so, you can use this option's dropdown list to set the polling notification's state: Enabled: The polling notification performs as scheduled. Suspended: The polling notification is removed from the scheduler. Disabled: The polling notification is removed from the scheduler. Note: Even if you enable the Run as True Listener option when you configure the MessageListener notification, the Suspended state is functionally identical to the Disabled state. The Suspend all enabled and Resume all suspended links help you change states quickly for multiple polling notifications.If there is no polling notification scheduled for a given adapter notification, control for this field is disabled. Use the icon to create a polling notification as described in step 6.
Edit Schedule	Click the icon to create or modify a schedule for a polling notification. Continue to step 6. Note: Before you can edit the schedule for a polling notification, you must first disable it.
View Schedule	To view the polling schedule for the selected polling notification, click the icon.Click Return to IBM webMethods Adapter for JMSNotifications to return to the main polling notification page.

To create or modify schedule parameters for the selected adapter notification, click on the

icon and provide values for the following parameters:

Field	Description/Action
Interval (seconds)	Type the polling interval time in seconds.
Overlap	Do not use this option; otherwise, an exception is generated and you could potentially receive duplicate messages from a topic.
Immediate	Select this option to start polling immediately.

Click Save Schedule.
After you create a polling notification, you can enable it. Use the State or Enabled field described in step 5 to enable a polling notification.

Using the Exactly Once Notification Feature

Adapter notifications can use the Exactly Once notification feature. This feature ensures that notification data will not be duplicated even if a failure occurs during processing. This is achieved by assigning unique IDs for each publishable document. After a processing failure, Integration Server checks for duplicate records in storage and ignores any duplicate IDs.

To use the Exactly Once feature, you must enable client-side queuing in Integration Server. For details, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Note: You can only use this feature if the notification is used to publish a document, not if it is associated with a service.

Viewing Notifications

About this task

You use Designer to view a notification.

To view a notification

Procedure

Review the steps in Before Configuring or Managing Notifications.
In Designer, expand the package and folder that contain the notification you want to view.
Double-click the notification you want to view.

Designer displays the notification in the notification template's Adapter Notification Editor.

Editing Notifications

About this task

You use Designer to edit notifications.

You can change the connection associated with an adapter notification with the built-in service pub.art.notification:setPollingNotificationNodeConnection. For more information, see Changing the Connection for an Adapter Service or Notification at Design Time.

To edit a notification

Procedure

Review the steps in Before Configuring or Managing Notifications.
In Integration Server Administrator, enable the connection for the notification you want to edit. Refer to Enabling Adapter Connections for instructions on enabling connections.
In Designer, expand the package and folder that contain the notification you want to edit.
Select the notification you want to edit.

Designer displays the notification in the notification template's Adapter Notification Editor.
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.
Modify the values for the notification's parameters as needed. For detailed descriptions of the notification's parameters, see the section on configuring a notification for the specific type of notification you want to edit.

Note: When you edit a notification, all the parameters in the adapter notification are reset.
After you complete 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.

Deleting Notifications

About this task

You use Designer to delete adapter notifications.

To delete a notification

Procedure

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