Receiving EMS messages

Receiving EMS messages involves configuring subscriber options, determining whether to watch or participate, configuring message content, and optionally, setting up filtering.

About this task

When you are receiving messages by using EMS, you must configure the subscriber options, message content, and optional filtering.

Note: You can record all traffic from a TIBCO EMS server thus removing the requirement to specify in advance which server operations are to be recorded.

Procedure

Configure subscriber options.

Receive Request options for receiving messages by using the EMS transport are managed under Receive Request Configuration.

The Receive Request options are described in the following table:


Option	Description
Destination	The destination queue or topic to monitor for incoming messages.
Durable	Enable this option and enter a name to create a durable subscriber, which ensures that messages are received even if the message consumer is not currently running.
Message Selector	Filters incoming messages according to message header properties.
Watch or Participate	You can either watch or participate in queue messaging subscriptions.

Determine whether you are going to watch or participate.
By using the EMS transport, you can either watch or participate in queue messaging subscriptions.

Note: The watch/participate option is not available when you are using the generic JMS transport.

Participate

In Participate mode (default), messages are pulled off the queue. Which can be undesirable in a testing scenario since a JMS queue message can go to only one connected client. In this case, the HCL OneTest™ API connection prevents other systems from receiving the messages. If this option is a problem, use the Watch option.

Watch

In Watch mode, HCL OneTest™ API receives new messages without removing them from the queue (that is, you can passively access messages without affecting the queue itself). To "watch" a queue, HCL OneTest™ API subscribes to system monitor topics (that is, the transport login configuration must have administrative rights on the EMS server it is watching).

Note: If security policies prohibit access to the server with full administrative privileges, request access to a limited number of queues. In other words, request access only to the specific queues that are needed for testing.

Note: The "Use JNDI to look up destination" option must be disabled when in "watch" mode (see Configuring the EMS transport).

Individual queue permissions

The EMS system administrator might prevent you from connecting to the server with full administrative rights. Such rights could e considered a security risk because you would be able to access any message. If necessary, you can request that permissions be added to your user account to allow access to specific queues. For example, the tibemsadmin command to grant permissions to watch queue.sample would be:
```
grant topic $sys.monitor.Q.*.queue.sample user=testuser subscribe
commit
```
The wildcards * and > can be used to give permissions across a number of queues, for example: grant topic $sys.monitor.Q.*.queue.* user=testuser subscribe
Configure message content.

The contents and structure of an EMS message body varies according to the message type. To set the type of messages to receive, select one of the options available from the Message Type dropdown menu.

For more information, see API Tester Reference.
Optionally, set up filtering.
You can filter the way messages are received in two different ways:
- JMS filtering
- Rational® HCL OneTest™ API filtering
.
Note: When you are using filtering, the system under test must be correctly configured. Messages that are filtered out are silently discarded. HCL OneTest™ API does not produce any warnings or errors.

JMS filtering

The Message Selector field under Receive Request Configuration accepts standard JMS filtering expressions (message selectors). When used, HCL OneTest™ API receives only messages that match the specified filter.

For example, if MyId='585858' is added to the Message Properties, only messages with the header field "MyId" having a value of 585858 are received. To send matching messages in a HCL OneTest™ API publisher, you would configure a message property as shown:

Note: Filtering is performed on message header properties, and matching messages are passed to HCL OneTest™ API (that is, the EMS server filters the messages, not HCL OneTest™ API). This option is useful in environments that share a single EMS queue or topic. By getting the applications to set header properties, you can separate messages logically. HCL OneTest™ API can interact with messages from Application A without affecting the messages of Application B.

HCL OneTest™ API filtering

After messages pass to HCL OneTest™ API, they can be further filtered (by using header and body fields) with the configuration in the Filter tab.

In this case, JMSDestination must equal "business.inventory global" and JMSCorrelationID must equal "32458". Otherwise, HCL OneTest™ API discards the message.