Show TOC

Configuring the Receiver JMS AdapterLocate this document in the navigation structure

Use

You configure the receiver JMS adapter to be able to convert PI messages from the Integration Server or the PCK into JMS messages.

Procedure
...
  1. Under Transport Protocol, select the JMS provider:
    • SonicMQ JMS Provider
    • WebSphereMQ (MQ Series) JMS Provider
    • JNDI JMS Provider Lookup
    • JMS Provider Administered Objects via File
    • Generic JMS Provider
  2. Select the Message Protocol as JMS 1.x.
  3. Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine.

    This selection is not available in the PCK.

Defining Connection Parameters

  1. Select the Target tab page.
    Note
    For Generic JMS Provider, 
    connection settings are specified in thetable.
    Additional Parameters
  2. If you want to connect to a JMS topic, select the Enable the Topic Support checkbox.

By default, JMS provider enables the queue support.

  1. Depending on the transport protocol you have selected, enter the connection parameters for the JMS provider.

Extra connection parameters can be specified in the Additional Parameters table of the Advanced tab page. Depending on the third party JMS provider, you may need to set a unique ClientID (for each channel) using the additional parameter table.

The function for setting the ClientID is provider-specific.

Defining Connection On Demand

  1. From the Transport Protocol dropdown listbox, choose WebSphereMQ (MQSeries) JMS Provider.
  2. Select the Create Connection on Demand checkbox.
  3. In the Connection keep alive (secs), specify a value that determines the duration of the connection.
    Note
    • The keep alive period determines how long the connection must be kept open after the delivery of a message.
      • If the value is zero, the JMS receiver adapter opens the connection and closes it immediately after delivering the message.
      • If the value is greater than zero, the JMS receiver adapter opens the connection for the first incoming message, delivers the message and closes the connection after the keep alive period lapses. If there are subsequent messages received during this active connection period, the adapter delivers these messages, resets the keep alive period everytime it delivers a message. and closes the connection after the keep alive period lapses for the last delivered message.
    • The JMS receiver adapter cannot reconnect automatically to the JMS provider in the event of the provider failure.

Initial Context Properties

  1. Specify the Initial context properties name and value in the table. Before SAP NetWeaver PI 7.20 release, initial context properties could be specified in the Additional Parameters table.

    Now this can be specified as:

    Name

    Value

    propertyName

    propertyValue

    Both propertyName and propertyValue are Strings.

    Note

    This table is available only if you select the Transport Protocol as JNDI JMS Provider Lookup .

Defining JMS Settings

  1. Select the Processing tab page.
  2. If you want to use a transactional JMS session, select Transactional JMS Session.

    The transactional JMS Session is the default setting and is recommended. If you do not use this setting, then the message delivery is not guaranteed.

    The message can be lost in such a case

    Following processing of a message, a transactional session ends either with a COMMIT, or in the case of an error, with a ROLLBACK.

  3. Select the Delivery Mode of Message Producer:
    • Persist JMS Messages in the JMS Provider
    • Do Not Persist JMS Messages in the JMS Provider
  4. Under JMS ReplyTo Queue Name, specify the name of the queue to which the responses are to be sent.
  5. Under JMS Message Expiration Period (msecs), specify the expiry period of the JMS message in milliseconds.
  6. Specify the JMS Message Priority (optional).
  7. Enter theUser and the Password with confirmation for accessing the JMS Queue/Topic.

Defining Correlation Settings

  1. Set the JMS Correlation IDto:
    • PI Message ID (MessageID) (default value)
    • PI Reference ID (RefToMessageID)
    • PI Conversation ID (ConversationID)
    • No value
  2. If you want to save the JMS correlation ID of the request, select Store JMSCorrelationId of Request.
  3. Specify what the JMS Property is to be set to.
  4. Select the Value of the JMS Property:
    • PI Message ID (MessageID) (default value)
    • PI Reference ID (RefToMessageID)
    • PI Conversation ID (ConversationID)
    • No value

Defining PI Settings

  1. Select the Mapping of Message:
    • If you only want the JMS payload to contain only the payload of the PI message, choose Message Payload = JMS Payload. (default setting)
    • If you want the JMS payload to contain the entire PI message, choose Entire Message = JMS Payload.
  2. The adapter can identify whether the connection has been terminated between the JMS commit and the commit in the database of the Adapter Framework. The adapter identifies the resulting duplicate data record.

    Select Handling of Pending PI Messages:

    • Throw Exception (Message Retry Possible Later)(default)
    • Bypass Pending Warning and Send Message to JMS (Duplicates Possible)

      A duplicate data record is created if the JMS commit is executed, but not the commit in the database of the Adapter Framework. If you select this option, you must make sure that this message has not yet been received in the JMS environment.

    • Mark Message as Delivered (Message Loss Possible)

      The message is lost if the JMS commit is not yet executed. If you select this option, you must make sure that this message has already been received in the JMS environment.

      Note

      For an example of how this parameter is used, see below under Example.

  3. Under Time Period for Duplicate Check for EO(IO) (secs), specify when the IDs are to be deleted.

    To check for duplicate messages, IDs must be saved in the database. To prevent the database from getting unnecessarily large, these IDs are deleted after a certain amount of time.

    For example, if you check message monitoring daily, deletion can take place after one day.

  4. If the JMS receiver is an application, the JMS adapter should return a delivery acknowledgment. Select Send PI Delivery Acknowledgment (Adapter Is Endpoint).

Defining Error Handling Settings

  1. Under Wait Timer After Message Error (msecs), enter the number of milliseconds that the adapter must wait when a processing error occurs, before further messages are processed.

    In transactional processing, for example, it can make sense to specify a certain time period, because messages with errors remain in the queue following a ROLLBACK.

  2. Under Wait Before Reconnect (msecs), specify a period of time after which an attempt is made to reestablish a connection following a connection error on the JMS side.

    If you enter -1, no attempt is made to reestablish the connection.

    Your JMS provider must support the registration of an ExceptionListener for this.

  3. If the JMS provider does not call the ExceptionListener registered by the JMS adapter when a connection error occurs, you can force the connection to be reestablished by setting the parameter Reconnection if Exception Text Starts with.

    If a JMS exception is thrown when sending a message, the free text specified here is compared with the specified string. Once the period of time specified in Wait Before Reconnect (msecs) has passed, an attempt is made to reestablish the connection.

    Note

    Only set this parameter if your JMS provider does not support the registration of an ExceptionListener.

Defining Adapter-Specific Message Properties

  1. Select the Advanced tab page.
  2. To evaluate adapter-specific properties in the message header of the PI message, select Use Adapter-Specific Message Properties.
  3. If you want missing message attributes to trigger an error message, select Fail On Missing Adapter Message Properties.

    If the indicator is set and the header for adapter-specific message attributes or one of the set attributes is missing from the message, this leads to a delivery exception in the audit log of the message.

    If you do not set the indicator, and message attributes are missing, the adapter accesses information from the adapter configuration.

  4. To evaluate the following attributes in PI message headers, set the corresponding indicators:
    • JMS Message Correlation ID: (technical name: DCJMSCorrelationID)
    • JMS Message Expiration: (technical name: DCJMSExpiration)
    • JMS Message Priority: (technical name: DCJMSPriority)
    • JMS Message ReplyTo Destination: (technical name: DCJMSReplyTo)
    • JMS Message Time stamp: (technical name: DCJMSTimestamp)
  5. If you want to set additional JMS message attributes, select Specify Additional JMS Message Properties (Maximum of 10).
    • In the table, enter the Name and Java Type of the JMS message properties whose values are to be included in the message header of the PI message.

      Under Java Type, you define the JMS Java message type for the attribute in the created JMS message. You can enter the following:

      • boolean
      • byte
      • short
      • int
      • long
      • float
      • double
      • string

    The technical names of the additional attributes are DCJMSMessageProperty0, DCJMSMessageProperty1, ..., DCJMSMessageProperty9.

    You can enter more than ten properties in the table. However, only the first ten are taken into account.

    The attribute namespace for the adapter is http://sap.com/xi/XI/System/ JMS.

Defining the Adapter Status

  1. Set the adapter to 
    Active
    to enable messages to be exchanged.

Defining Additional Parameters

  1. Specify the additional parameter Names and Values in the table.

    For example, if you are connecting to a third party JMS provider you can enter the client ID and its corresponding value for each channel. However, these are specific to the third party provider.

    For more information refer to the documentation of the third party provider.

Example

Below is a typical procedure for handling pending messages:

...
  1. The default setting for the parameter of the receiver JMS adapter is Throw Exception.
  2. You see the following exception in the message or adapter monitor:

    The channel is configured to throw a recoverable, temporary error for this warning (default). Decide whether you want to bypass this message. If so, set the Pending Handling channel parameter to 'Bypass' and restart the message afterwards.

  3. Make sure that no further messages are sent through this communication channel by deactivating the corresponding sender channel.
  4. Check whether the message or messages have arrived in the JMS environment.
    1. If the message has arrived in the JMS environment, select Mark Message as Delivered (Message Loss Possible).
    2. If the message has not arrived in the JMS environment, select Bypass Pending Warning and Send Message to JMS (Duplicates Possible).
    3. Choose Repeat in message monitoring.

      If some messages have arrived in the JMS environment and some have not, you must perform the procedure twice and resend the respective messages in each case.

  5. Reset the parameter in the communication channel to Throw Exception.
  6. Activate the corresponding sender communication channel.