QLT - Tracking Objects

The QLT component is the implementation of the QLT protocol. It opens a port, listens for events, triggers Camel exchanges with the events and finally sends the response. Learn how to work with the QLT component.

Definitions

Tracking Object defines a template of monitoring events sent by several Axway products. A monitoring event contains a set of key/values defined in the Tracking Object.

These monitoring events are transferred over the network using the QLT protocol. This protocol exists in 2 versions (QLTv1 and QLTv2) which are both natively supported by Decision Insight (no additional library needs to be imported). Decision Insight automatically detects the version of the protocol and provides a uniform way of receiving and reading the events no matter which version was used. The QLT protocol can also be encyrpted using SSL.

The QLT component

The QLT component is the implementation of the QLT protocol. It opens a port, listens for events, triggers Camel exchanges with the events and finally sends the response.

It implements the QLT protocol the same way as camel-jetty or camel-http4 implements the HTTP protocol.

The QLT component can receive monitoring events using the QLTv1 and the QLTv2 on the same port.

Once an event is received, it creates a Camel exchange with the binary version of the event (as byte array) in the body.

When the processing of the Camel exchange is complete, it automatically sends the response:

  • ACK response if the processing was successful.
  • NACK response if the processing threw an exception.

The QLT data format

The QLT data format decodes the binary representation of a monitoring event. This binary version can come directly from the QLT component or from any intermediate storage of monitoring events.

It creates a Map with the key/values that are defined in the monitoring events.

Receiving monitoring events

In order to receive monitoring events you need to use the QLT component using the qlt component name.

QLT component usage

Here is a sample usage of the QLT component.

Routes definition
<routes xmlns:u="http://www.systar.com/aluminium/camel-util" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="qlts:0.0.0.0?sslContextParameters=#sslConnector" />
        <!-- without TLS: <from uri="qlt:0.0.0.0" /> -->
        <log message="Just received an event with a ${body.class.simpleName} body." />
    </route>
</routes>

When this route is started and some events are sent you have the following logs:

2016-03-04 15:44:23,402 INFO com.axway.adi.qlt.event.listener.QltEventConsumer - Starting the QLT server
2016-03-04 15:44:23,614 INFO com.axway.adi.qlt.event.listener.QltEventConsumer - QLT server is started
2016-03-04 15:44:37,001 INFO route1 - Just received an event with a byte[] body.
2016-03-04 15:44:37,027 INFO route1 - Just received an event with a byte[] body.

After the <from /> tag you can use any processing you want.

Configuration

Configuration of the network interface

The network interface to listen to is configurable right after the qlt{s}: prefix ( {s} needed for TLS connections). Here are some examples:

URI Description
qlt{s}:0.0.0.0 Listen to all network interface of the server
qlt{s}:localhost Listen only to localhost network interface, you can only receive events that are sent by the same server
qlt{s}:10.11.12.13

Listen only to the network interface that has the 10.11.12.13 IP address.

If the server has another IP address it throws an exception and the route doesn't start

qlt{s}:server.company.com

Listen only to the network interface that has server.company.com as DNS name

If the server doesn't have this DNS name it throws an exception and the route doesn't start

Configuration of the network port

By default it uses the 1305 port but you can specify which port to use. Here are some examples:

URI Description
qlt{s}:0.0.0.0 Listen to the default port (1305)
qlt{s}:0.0.0.0:1305 Listen to the 1305 port
qlt{s}:0.0.0.0:12345 Listen to the 12345 port

With TLS

Here is a sample usage of the QLT component with TLS.

Routes definition
<routes xmlns:u="http://www.systar.com/aluminium/camel-util" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="qlts:0.0.0.0?sslContextParameters=#sslConnector" />
        <log message="Just received an event through SSL with a ${body.class.simpleName} body." />
    </route>
</routes>


To receive events through SSL you need to use the 
QLT component  using the  qlts  component name. The parameter for configuring the SSL context is named  sslContextParameters  and its type is the  SSLContextParameters  from Apache Camel. The parameter value is the name of the connector that holds the configuration.

For information about how to configure the SSL connector, see How to configure SSL on a component.

Without TLS

TLS configuration

Although it is not mandatory, we advise you to always configure TLS connection and forbid non encrypted communication. If not configured:

  • data are not encrypted
  • without mutual authentication, you cannot ensure that connected clients are trusted
Routes definition
<routes xmlns:u="http://www.systar.com/aluminium/camel-util" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="qlt:0.0.0.0" />
        <from uri="qlt:0.0.0.0:1306" />
        <log message="Just received an event with a ${body.class.simpleName} body." />
    </route>
</routes>

If you use multiple <from /> tags in your route you can listen to several ports at the same time and have the same processing.

Decoding monitoring events

To decode monitoring events, the QLT data format using the qlt data format name.

QLT data format usage

Here is a sample usage of the QLT data format:

Routes definition
<routes xmlns:u="http://www.systar.com/aluminium/camel-util" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="qlt:0.0.0.0" />
        <to uri="dataformat:qlt:unmarshal" />
        <log message="Just received an event with the following content: ${body}" />
    </route>
</routes>

After the decoding (using <to uri="dataformat:qlt:unmarshal" />), the body of the Camel exchange will be a Map with:

  • the mandatory values of the events: EVENTDATEEVENTTIMEPRODUCTNAMEPRODUCTOSPRODUCTIPADDR and GMTDIFF
  • the values defined in the tracking object

For instance, when this route is started and some events are sent you have the following logs:

2016-03-04 16:11:02,183 INFO com.axway.adi.qlt.event.listener.QltEventConsumer - Starting the QLT server
2016-03-04 16:11:02,422 INFO com.axway.adi.qlt.event.listener.QltEventConsumer - QLT server is started
2016-03-04 16:11:08,344 INFO route1 - Just received an event with the following content: {EVENTTIME=16:11:07, PRODUCTOS=Windows 8.1, EVENTDATE=2016-03-04, ATTR3=value3, ATTR2=value2, ATTR1=value1, PRODUCTNAME=TRKAPIUA, GMTDIFF=60, PRODUCTIPADDR=}
2016-03-04 16:11:08,356 INFO route1 - Just received an event with the following content: {EVENTTIME=16:11:08, PRODUCTOS=Windows 8.1, EVENTDATE=2016-03-04, ATTR4=value4, PRODUCTNAME=TRKAPIUA, GMTDIFF=60, ATTR6=value6, PRODUCTIPADDR=, ATTR5=value5}


In order to decode the monitoring event, do not use the <unmarshal> tag because Camel hardcoded the list of data formats that can be used in this tag.

Instead, use the data format component that can load any data format with the <to uri="dataformat:qlt:unmarshal" /> notation.

Configuration

Configuration of the charset to use in order to read the event

You can specify the charset to use by using the charset parameter. Here are some samples:

URI Description
dataformat:qlt:unmarshal?charset=ISO-8859-1 Uses the ISO-8859-1 charset for reading the event
dataformat:qlt:unmarshal?charset=UTF-8 Uses the UTF-8 charset for reading the event
dataformat:qlt:unmarshal

Uses the charset defined in the XML event payload. If undefined it uses the algorithm from the XML specification in order to find the encoding.

Headers

When you decode a monitoring event ,the following headers are added to the exchange:

Header Description
TrackingObjectXmlVersion The version of the XML representation
TrackingObjectType The type of the monitoring event
TrackingObjectName The name of the monitoring event
TrackingObjectVersion The version of the monitoring event

Manual configuration of the ACK/NACK response

Default behavior

When the Camel processing is completed, if an exception was thrown and interrupted the flow of processing then a NACK response is automatically sent. If no exception was thrown then it sends an ACK response.

In Camel you can manually:

  • throw a new exception using the <throwException> tag
  • catch thrown exceptions using using the <doTry> and <doCatch> tags

Therefore, when combining those tags you can tune when to send a ACK and when to send a NACK

Catch all errors

In this example, we're going to catch all errors, write them to disk as their original binary representation. Since we're catching the exception, it will automatically replies with ACK responses

Routes definition
<routes xmlns="http://camel.apache.org/schema/spring" xmlns:u="http://www.systar.com/aluminium/camel-util">
    <route>
        <from uri="qlt:0.0.0.0"/>

        <!-- Save the raw version of the event in case of error -->
        <setHeader headerName="raw">
            <simple>${body}</simple>
        </setHeader>


        <!-- Try to process the event -->
        <doTry>
            <to uri="dataformat:qlt:unmarshal"/>
            <to uri="direct:process"/>
            <doCatch>
                <!-- Catch all exceptions -->
                <exception>java.lang.Exception</exception>
                <!-- Set the body back as the raw version of the event -->
                <setBody>
                    <header>raw</header>
                </setBody>
                <!-- Write the events in the "errors" directory -->
                <to uri="file:errors"/>
            </doCatch>
        </doTry>
    </route>

    <route>
        <from uri="direct:process" />
        <!-- Add processing here -->
    </route>
</routes> 

Throw an exception based on a business rule

In this use case we're going to manually send an exception based on a business rule in order to reply with a NACK response

Routes definition
<routes xmlns="http://camel.apache.org/schema/spring" xmlns:u="http://www.systar.com/aluminium/camel-util">
    <route>
        <from uri="qlt:0.0.0.0"/>
        <to uri="dataformat:qlt:unmarshal" />
        
        <choice>
            <when>
                <simple>${header[TrackingObjectName]} == 'XFBTransfer'</simple>
                <to uri="direct:processXFBTransfer" />
            </when>
            <otherwise>
                <throwException exceptionType="java.lang.UnsupportedOperationException" message="Unsupported tracking object (name=${header[TrackingObjectName]})" />
            </otherwise>
        </choice>
    </route>
 
    <route>
        <from uri="direct:processXFBTransfer" />
        <!-- Add processing here -->
    </route>
</routes> 

Related Links