TIF Server - Destinations

01 February 2013

Table of Contents

1. Configure Destinations

1. Configure Destinations

Transferring data to another system requires you to declare the destination endpoints somewhere. This is done within one centralized file located at ${TIF_ROOT}/etc/destinations.xml.

This file is not part of the installation, instead, we provide an example configuration called ${TIF_ROOT}/etc/destinations.xml.sample.

This configuration file is of XML format, and the root element of this file is <Destinations>.

The currently supported destinations are:

File: Used to store data into a generated file inside a particular directory
FTP: Transfer data to a FTP site
Email: Transfer data via mail to a recipient
HTTP: Used to transfer the data to some destination via HTTP protocol. E.g. a REST service or similar.
SOAP Service: A defines SOAP endpoint.
JMS: Used to transfer the data to a JMS topic or queue.
Rabbit MQ (AMQP): Used to transfer the data to a Rabbit MQ server via the AMQP protocol.
Websphere MQ / Native MQ: Used for transfer the data to a IBM-MQ broker via the Native-MQ protocol. Note that IBM MQ also supports the JMS protocol.

Each destination within this configuration file is associated with an identifier. This identifier must be unique across all destinations.

Example: ${TIF_ROOT}/etc/destinations.xml

<Destinations>

    <JMS id="erp-01"
         initialContextFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
         providerURL="tcp://erp01.company.com:61616">
        <Queue name="released_parts" jndiKey="queue.%s"/>

        <Env key="..." value="..."/>
        <Env key="..." value="..."/>
    </JMS>

    <RabbitMQ id="SAP"
              uri="amqp://userName:password@hostName:portNumber/virtualHost"
              routingKey="rk1">
        <Queue name="q1" autoDelete="false" durable="true" exclusive="false"/>
        <Exchange name="e1" autoDelete="false" durable="true" type="direct"/>
    </RabbitMQ>

</Destinations>

The implementation specific JAR files should be stored inside the folder ${TIF_ROOT}/lib/custom

1.1. File Destination

A file destination is used to define a location where files are either written to or read from.

Below is an example configufiration of a File destination.

<Destinations>
    <File id="file1"
          directory="/var/transfer/tif"
          filePrefix="ECO_"
          fileSuffix=".xml"/>
</Destinations>

The table below shows the available attributes on the File destination element.

Attribute Description Required

Attribute	Description	Required
id	A unique identifier.	Yes
directory	The directory, which the files will be generated inside. You may use the following macros inside the value: `${tif.home}` The base directory of the TIF server `${tif.temp}` The temp directory for the TIF server Use absolute paths, unless using a macro.	Yes
filePrefix	The prefix, which the generated file will get. Note The length of the prefix must be at least three characters long.	No
fileSuffix	The suffix, which the generated file will get.	No
fileName	A static filename to be used if you want this destination to use the same file over and over again.	No
append	True/false to append data. May be useful in combination with the fileName attribute	No

A unique identifier.

Yes

1.2. HTTP Destination

A HTTP destination is used to transfer data into a remote server via HTTP.

Below is an example configuration of a HTTP destination that transfers data via HTTP/POST.

<Destinations>
    <Http id="http-1"
          url="http://server:port/app/servlet/test"
          retryCount="3"
          retryDelay="3000"
          timeout="30000">
        <Header name="Authorization" value="Bearer ABCDEF" />(1)
    </Http>
</Destinations>

1	Optional headers can be applied

The table below shows the available attributes on the HTTP destination element.

Attribute	Description	Required
id	A unique identifier.	Yes
url	The URL of the HTTP endpoint that will receive the data.	Yes
retryCount	The number of times to retry sending if the remote server does not answer	No
retryDelay	The delay in ms to wait between to retry attempts	No
timeout	The connect timeout in ms	No
method	Request method. Default is POST if not defined.	No

Attribute

Description

Required

A unique identifier.

Yes

url

The URL of the HTTP endpoint that will receive the data.

Yes

retryCount

The number of times to retry sending if the remote server does not answer

retryDelay

The delay in ms to wait between to retry attempts

timeout

The connect timeout in ms

method

Request method. Default is POST if not defined.

The HTTP destination also supports authentication using either Basic or Digest methods. Below is an example illustrating how to accomplish this.

<Destinations>
    <Http>
        <Authentication> (1)
            <Basic/> (2)
            <UserName>name of user</UserName> (3)
            <Password>the password</Password> (4)
            <Realm>the realm</Realm> (5)
        </Authentication>
    </Http>

1	Defines the authentication block
2	Either Basic or Digest can be used
3	Specifies user name
4	Specifies the password
5	Specifies the authentication realm

1.2.1. SSL Configuration

By default, all SSL certificates are trusted when transferring data to HTTPS destination. To improve security, you can change the behavior by configuring settings in ${TIF_ROOT}/etc/tif.custom.properties.

To configure settings, it is required to stop trusting all certificates:

https.client.disableTrustAll=true

When https.client.disableTrustAll is set true, the available settings are:

https.client.keyStore.path=<path to keystore, example: etc/keystore>
https.client.keyStore.password=secret
https.client.keyStore.type=
https.client.keyStore.provider=
https.client.keyManager.password=
https.client.trustStore.path=<path to the trust-store, example: etc/keystore>
https.client.trustStore.password=secret
https.client.trustStore.type=
https.client.trustStore.provider=
https.client.includeCipherSuites=<comma separated list>
https.client.excludeCipherSuites=<comma separated list>

At least a keystore and the password needs to be configured.

1.2.2. Preempt Basic Authentication

By default, when transferring data to a HTTP destination for the first time, TIF’s HTTP client does the following conversion with the destination:

The client sends a request.
The destination issues a challenge by responding with status code 401 and the header "WWW-Authenticate".
The client sends similar request, but with "Authorization" header.

If the authentication is successful, it is cached and reused for subsequent requests.

It is possible to preempt basic authentication by setting attribute preempt to true in element <Authentication>. In this case, the "Authorization" header is added immediately to the request without additional roundtrip to the destination.

1.3. JMS Destination

An example JMS destination is shown below:

<Destinations>
    <JMS id="jms-1"
         initialContextFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
         providerURL="tcp://server:61616">

        <Queue name="TestQueue1" jndiKey="queue.%s"/> (1)
    </JMS>

1	The JMS element must contain either a `<Topic>` or a `<Queue>` child element.

The attributes, which the JMS elements support, are shown in the table below:

Attribute Description Note

Attribute	Description	Note
id	A unique identifier.
initialContextFactory	The fully qualified name of the class that your JMS provider provides as InitialContextFactory.	The JAR files that your JMS provider provides, should be put inside the folder `${TIF_ROOT}/lib/custom`.
providerURL	The URL to your JMS broker
user	Optional user name	Not required unless your JMS provider requires this when establishing the connection.
password	Optional password
connectionFactoryKey	When looking up the ConnectionFactory from the JNDI registry, a key is used for this lookup. By default, the key is assumed to be `ConnectionFactory`, however, depending on what keys your JMS provider uses you might need to use a different lookup-key.	Not required.
extensionId	May be used to separate different implementation classes from each other. See below	Not required

A unique identifier.

initialContextFactory

The fully qualified name of the class that your JMS provider provides as InitialContextFactory.

The JAR files that your JMS provider provides, should be put inside the folder ${TIF_ROOT}/lib/custom.

providerURL

The URL to your JMS broker

user

Optional user name

Not required unless your JMS provider requires this when establishing the connection.

password

Optional password

connectionFactoryKey

When looking up the ConnectionFactory from the JNDI registry, a key is used for this lookup.

By default, the key is assumed to be ConnectionFactory, however, depending on what keys your JMS provider uses you might need to use a different lookup-key.

Not required.

extensionId

May be used to separate different implementation classes from each other. See below

Not required

The Queue or Topic element may have these attributes:

Attribute Description Note

Attribute	Description	Note
name	The name of the queue or topic to use	Required
jndiKey	The key used to lookup this destination from the JNDI registry. By default this value is `queue.%s` for a queue and `topic.%s` for a topic. Note that `%s` is a macro referring to the name of the queue/topic itself. If your JMS provider uses a different naming convention for the JNDI lookup key of the destination, you need to configured this attribute accordingly.	Optional

name

The name of the queue or topic to use

Required

jndiKey

The key used to lookup this destination from the JNDI registry.

By default this value is queue.%s for a queue and topic.%s for a topic. Note that %s is a macro referring to the name of the queue/topic itself.

If your JMS provider uses a different naming convention for the JNDI lookup key of the destination, you need to configured this attribute accordingly.

Optional

Additional JNDI environment variables can be set via nested <Env> elements as shown below. This element supports two attributes: key and value. Example:

<JMS ...>
    <Queue name="testqueue" jndiKey="destination.%s"/>
    <Env key="a key" value="a value"/>
    <Env key="another key" value="another value"/>
</JMS>

1.3.1. Separation of Classes

Normally, the JMS provider specific classes should be put into ${TIF_HOME}/lib/custom. However, if there are some collisions of classes, one can instead put these into a folder like this ${TIF_HOME}/extensions/<name-of-extension>.

Then you need to specify the name of the extension on the extensionId attribute on the JMS destination itself.

So if you put your implementation JAR files below ${TIF_HOME}/extensions/sib then your JMS destination needs the attribute extensionId="sib".

1.4. Rabbit MQ Destination

An example RabbitMQ destination is shown below:

<Destinations>
    <RabbitMQ id="rabbitmq-1"
          uri="amqp://userName:password@hostName:portNumber/virtualHost"
          routingKey="rk1">
        <Queue name="q1" autoDelete="false" durable="true" exclusive="false"/>
        <Exchange name="e1" autoDelete="false" durable="true" type="direct"/>
    </RabbitMQ>

The attributes for the <RabbitMQ> element is described in the table below:

Attribute	Description	Note
id	A unique identifier.
uri	The AMQP URI
userName	The user name	Not required if complete URI is defined
password	The password	Not required if complete URI is defined
hostname	The host name of the Rabbit MQ server	Not required if complete URI is defined
port	The port number of the Rabbit MQ server	Not required if complete URI is defined
virtualHost	The virtual host name	Not required if complete URI is defined
routingKey	The routing key to be used	This can typically be overridden when the RabbitMQ destination is being used
mandatory	The mandatory flag	Boolean (default: false)
immediate	The immediate flag	Boolean (default: false)

Attribute

Description

Note

A unique identifier.

uri

The AMQP URI

userName

The user name