WebSphere MQ agent settings

This dialog box enables you to configure the Service Virtualization WebSphere MQ agent. The agent handles communication between a client and a real or virtual service.


To access
  1. From the main menu, select Tools > Options.
  2. Click Agents.
  3. Under WebSphere MQ, select a configuration.
Important information
  • For additional important configuration information, see the task Configure the WebSphere MQ agent.

  • The WebSphere MQ Agent instance represents a connection to a single WebSphere MQ queue manager. A virtual service can use multiple agent instances if it needs to access queues on multiple queue managers.

  • The WebSphere MQ Agent is able to automatically reconnect when a connection to the WebSphere MQ Server is lost.
  • You can define multiple configurations for each agent.

Relevant tasks

Configure agents

See also Service Virtualization agents

Back to top

User interface elements

User interface elements are described below (unlabeled elements are shown in angle brackets):

UI Element Description
<left pane>

Displays the server configured for your project.

Expand the server to display the available agents and configurations.


Enables you to define additional configurations of the agent.

Delete Deletes the selected configuration.

Creates an additional configuration of the agent by copying the selected configuration. You can then modify the configuration settings.


Saves the selected agent configuration as a file. The file is saved in the .agce file format, and can be imported to any Service Virtualization Server.

Export All Exports all agent configurations on the selected server. The file is saved in the .agce file format, and can be imported to any Service Virtualization Server.

Enables you to select an exported agent configuration file stored on the file system. The file is saved in the .agce file format, and can be imported to any Service Virtualization Server.

If the configuration file you are importing contains multiple configurations, you can select which configurations you want to import.

If you choose to import an agent configuration that is identical to a configuration that already exists on your server, you can choose to overwrite your existing configuration, or create a new, additional configuration.

Agent State The current status of the agent. Values include Running, Not Running.
Test Configuration link Tests the configuration based on the settings you select. If Service Virtualization identifies any problems in your configuration, the details are displayed.
Is Enabled Turns the agent on and off. To enable the agent, the prerequisites must first be met.
Name Enter a name for the agent instance or accept the default name.
Local Connection

If the Service Virtualization Designer or Server is running on the same machine as the WebSphere MQ server, you can use a direct local connection to the MQ queue manager. Using the local connection may have a positive impact on performance and simplifies agent configuration.

Local Connection allows direct connection to the queue manager specified by the Queue Manager Name property

If you select this option, you do not need to configure the Host, Port, Channel Name, or SSL properties.

Queue Manager Name

The name of the queue manager for the agent to connect to. This option is necessary only if Local Connection is used.

Channel Name

The name of the TCP channel for the agent to use to connect to the queue manager.


The name or IP address of the server hosting the queue manager.

Port The TCP port where the channel listens for client connections.

The character set used by the host. It may be optional depending on the WebSphere MQ configuration.


The username and password for connecting to the queue manager.

These values may be optional depending on the MQ channel configuration. For details, see MQ authentication.

SSL Protocol Secure protocol used for the MQ Server connection. For details, see SSL Configuration.
MQ Channel Root CA File

Path to a certificate file of the Root Certificate Authority which signed the SSL certificate bound to the MQ channel, or to a self-signed MQ channel certificate. Supported formats are Base64 PEM, and binary CRT (supported on Windows only).

This certificate is added to the 'Trusted Root Certificate Authorities' certificate store. If the Service Virtualization Designer and Server are run "as Administrator", it puts the certificate in the Local Machine store; if the Designer is run as a non-admin user, it puts the certificate into the Current User certificate store.

You can leave this property empty if the MQ channel certificate is already trusted by a machine running Service Virtualization.

Max. Connections The maximum number of cached connections to the queue manager allowed for handling messages. More connections enable more messages to be sent concurrently.
Advanced Settings
Message Context Mode

Options for accessing the MQ queue. See the WebSphere MQ documentation for details.

  • None.
  • Set Identity. Corresponds to the MQC.MQOO_SET_IDENTITY_CONTEXT property.
  • Set All. Corresponds to the MQC.MQOO_SET_ALL_CONTEXT property.
Strip XML Declarations Removes XML declarations (<?xml ...>) from text messages before processing in Service Virtualization. Text messages are in Unicode.
Use UTF Methods

Service Virtualization considers MQ text messages as created by the WriteUTF() method instead of the WriteString() method.

When using an XML service, the message can be either transferred as a string (with a specified character set) or as binary data (UTF). By default, the agent reads and writes messages as a string. Select this option to use binary messages with UTF content instead.

Response Queue Access Mode

Defines how Service Virtualization opens the response queue.

  • Default. The Service Virtualization agent can access a shared queue, and selects messages in the queue according to FIFO methodology.

    Caution: Service Virtualization consumes messages regardless of the correlation mechanism (defined in the Request-Response Matching Mode field below). This can be problematic if the queue is shared. In this case, it is recommended to use the Shared mode.

  • Exclusive. Opens the queue in the MQ Exclusive Queue Access mode. Access is limited to Service Virtualization only, enabling the fastest sequential picking from the queue.
  • Shared. Opens the queue as an MQ shared queue and selects specific responses according to the IDs used for request-response matching mode (request message ID, request correlation ID, or both). Enables you to run several services with one response queue, or run a virtual service with systems where the response queue is shared with other applications.

    Note: This mode is slower than the other modes, as it is selecting specific responses from the queue and not simply the first response.

Listening Timeout (ms)

The length of time Service Virtualization listens for a response or multi-response. If the response does not arrive within the timeout period, Service Virtualization stops the listening process, even if there are multiple responses expected.

Maximum Responses per Request Defines the number of response messages that are expected for each request message. Relevant when the Service Virtualization agent is configured to use Shared Response Queue Access Mode only. When the maximum responses per request are reached, Service Virtualization stops the listening process.
Request-Response Matching Mode

Defines the method used to match a response to the correct request.

  • Request Message ID -> Response Correlation ID. The Message ID of the request is copied to the Correlation ID of the response. This is the default behavior of WebSphere MQ.
  • Request Correlation ID -> Response Correlation ID. The Correlation ID of the request is copied to the Correlation ID of the response.

Back to top

MQ authentication

The MQ Queue Manager can use two methods of authentication:

  • MQCSP authentication. To use this method, you enter the credentials into the Username and Password fields. These credentials are managed by the MQ administrator.

  • Authentication via the local user running the SV process. The MQ Queue Manager can be configured to use this method in addition to or instead of MQSCP authentication. When using this method, you leave the Username and Password fields empty.

Tip: You can configure the SV process to run under a dedicated user, to make it easier to grant user permissions. For details, see How to run SV Server under a different user.

For both authentication methods, the MQ administrator manages the permissions for the virtual agent. If you are granted certain permissions, you can browse and search Websphere MQ queues and create or delete virtual destinations. For details, see WebSphere MQ and Browse Destinations Dialog Box.

To browse MQ destinations, the specified user must be able to perform the following in the WebSphere MQ client:

  • put and inq operations on the SYSTEM.ADMIN.COMMAND.QUEUE

  • get, inq, and dsp operations on the SYSTEM.DEFAULT.MODEL.QUEUE

  • dsp operations on queues to which the user has access permissions

To create or delete a virtual destination, the user requires additional permissions, such as administrator permissions. For details, contact the MQ administrator.

Back to top