This article will provide details about the main features, deployment, setup and usage of JMS Connector for Secure Transport.

Table of contents

1. Overview of JMS standard
2. JMS Connector - main features
3. Installation
4. Initial Setup
5. Test Scenarios
6. Troubleshooting

Overview

The JMS (Java Messaging Service) API is a messaging standard that allows Java applications to create, send, receive and consume messages. It has many advantages, mainly:

Loosely Coupled - The JMS API has standard specification that should be implemented by all JMS Providers (e.g. ActiveMQ, AmazonSQS, etc). The JMS Provider could be changed to a new one, only with minor configurations, without changing the JMS application code.

Asynchronous - The JMS sender can send messages and continue its own operations/tasks, without the need to wait for completion of message consumption by the JMS receiver.

Robust/Reliable - JMS ensures that a message is delivered only once to the destination system.

JMS Connector - Main Features

Supports the main MFT flows - S2H (System to Human) and H2S (Human to System). In S2H ST sends messages to a JMS queue. In H2S ST receives messages from a JMS queue based on a scheduled subscription.

Uses a JNDI configuration - A context factory object is used to create a connection between the Java application and the JMS Provider. This feature allows the JMS Connector to work with different JMS Providers only by providing a context factory and a JNDI configuration.

Supports two different message delivery models:

Point-to-Point (Queue destination) - A message is delivered from one Producer to one Consumer. The message is delivered to a queue and then delivered to one of the consumers registered for the queue.

Publish/Subscribe (Topic destination) - A message is delivered from a producer to any number of consumers. Messages are delivered to a topic destination and then to all active Consumers that have subscribed to the Topic.

Installation

Download

The JMS Connector for ST can be downloaded from the Axway Marketplace from this link.

Prerequisites

Before proceeding further, check the Prerequisites section of the README.md file, which is available in the JMS Connector zip archive.

Remove previous deployments (if any)

Make sure that there are no files/folders from previous versions of the JMS Connector. For that purpose, check the <FILEDRIVEHOME>/plugins/transferSites/ folder, and remove the axway-site-jms.jar file and the /axway-site-jms sub-directory.

Unzip the package

Extract the zip archive with the JMS Connector securetransport-plugins-site-jms-<version>.zip into <FILEDRIVEHOME>/plugins/transferSites/.

Add a logger

You need to add a dedicated Transaction Manager (TM) logger (if it does not exist) for the newly deployed JMS Connector, so that events related to the Connector are available in the Server Log. Follow the steps below.

Take a backup copy of the <FILEDRIVEHOME>/conf/tm-log4j.xml file;

Open the <FILEDRIVEHOME>/conf/tm-log4j.xml file for editing;

Add the following logger in the beginning of the loggers section of the file, with the desired logging level:

<logger name="com.axway.st.plugins.site" additivity="false">
        <level value="info" />
        <appender-ref ref="ServerLog" />
</logger>

To enable debug logging, set the level value to debug. However, change the value with caution. It is recommended to switch to levels different than INFO only temporarily, e.g. during troubleshooting sessions.

Save the file

Restart ST's services

<FILEDRIVEHOME>/bin/stop_all

<FILEDRIVEHOME>/bin/start_all

Initial Setup

To configure the JMS connector, edit the <FILEDRIVEHOME>/plugins/transferSites/axway-site-jms/app.properties file on all SecureTransport Server nodes. This file contains the following configuration options:

tmp.folder - define the shared folder which is used for temporary storage of the received JMS messages. This folder must be shared between all ST nodes.

text.encoding - define the encoding that will be used when pushing files as JMS text messages. If not specified the platform default encoding is used.

Limitation: The connector can only consume topic messages as durable subscriber.

Create a Transfer Site under a user and select "JMS" from the Protocol drop-down. Use the tooltips in the JMS Transfer Site for more information about a particular field or option. The below section describes those options and fields, which are required and/or their tooltips don't offer sufficient details.

JNDI Configuration: The mandatory objects in this field are the Context Factory and the IP address of the server.

JNDI Encrypted Properties: if there are parameter values (e.g. password) that have to be added to the JNDI configuration, they could be inserted in the Property 1, 2, etc. fields.

Post Transmission Receive Options - Trigger Pull: This feature allows to read a message, evaluate a header or a property of the message, and then insert it in the Request Body for another pull initiated by ST. Example: Download a message with a specific filename and then we send the filename to another system to download the aforementioned file.

Test Scenarios

Server Initiated Push - Upload a message to a queue

• In the JMS Transfer Site, under "Upload Settings", in Destination type leave Queue selected;
• Under Message Type drop-down select Bytes;
• In Upload destination name define the queue of the JMS provider, where the message would be sent to;
• [optional] Use the Filename Header and Metadata map (key=value) pairs fields to add headers to the target message;
• Create a Subscription to a Basic Application or Advanced Router to utilize the JMS Transfer Site;
• Login to ST with the user account and upload a test file in the Subscription Folder. Wait for a few seconds;
• Go to Operations → File Tracking → Show Advanced Search, then filter by "Protocol: JMS" and make sure the transfer succeeded with green check Transfer Status icon;
• If all have succeeded, go to the JMS provider and check the queue and the message details.

Server Initiated Pull - Download a message by a given selector

• In the JMS Transfer Site, under "Download Settings", in Source type leave Queue selected;
• Under Download source name put the name of the queue, where the message would be downloaded from;
• Under Download message selector define the Message ID of the source message (e.g. JMSMesageID=’<the provider message id>’ );
• [optional] Use the Filename Header and Metadata map (key=value) pairs fields to download certain headers along with the target file;
• Create a Subscription to a Basic Application or Advanced Router to utilize the JMS Transfer Site;
• Wait for the scheduler to trigger or use the "Retrieve Files Now" button in the Subscription;
• Go to Operations → File Tracking → Show Advanced Search, then filter by "Protocol: JMS" and make sure the transfer succeeded with green check Transfer Status icon;

Troubleshooting

When a transfer to/from a JMS provider has failed, the steps below can be used as guidelines how to troubleshoot the issue. Yet, as a first step, you should always verify that the JNDI Configuration and the Download/Upload parameters (Queue/Topic name, Source/Destination names, Download Message Selector, etc) are correct and up to date.

• Go to ST's Admin UI → Operations → File Tracking, expand the "Show Advanced Search" and filter by File, or by Protocol: JMS, etc.
• Click on the red X Transfer Status icon related to the failed transfer, expand the window and take a screenshot of the entire content. The screenshot will be requested by Axway Support in case it is needed to open a Support ticket.
• Click on the SessionID link, which redirects to the Server Log with filtered results related to the transfer session.
• Add an additional filter for ERROR log level and hit Go.
• Inspect the messages related to the transfer session.
• The detailed error/root cause is likely to be presented in these event messages. Click on the timestamp link next to the message that might hold the error. Expand the window. Detailed error message/stack trace is presented.

In case the error does not provide an explanation what had happened, take a screenshot of the window mentioned in the last bullet point and/or export the log results using the "Export Log" button and open a ticket with Axway Support for further investigation. In case the Transaction Manager (TM) log is exported in flat file, send an archived copy of the TM log to Axway Support, along with the timeframe/timestamp details of the failed transfer.