01 February 2013

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

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

If your destination is used for writing data into, then either the fileName or filePrefix attributes must be used.

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

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

The password can be stored in encoded formats such as base 32 or base 64 values, or encoded using the ENOVIA MQL command "encrypt password". If a encoding strategy is used, the encoded password must be prefixed with the encoding format like this:

<Destinations>
    <Http>
        <Authentication>
            <Basic/>
            <UserName>name of user</UserName>
            <Password>b64:aGVsbG8gd29ybGQ=</Password>
            ...
        </Authentication>
    </Http>

The valid prefixes are:

  • plain

  • b64

  • b32

  • enovia

    • For passwords envoded with a MQL client prior to version 19xHF2

  • enovia-19x

    • For passwords encoded with a MQL client between the version 19xHF2 and 20x

  • enovia-21x

    • For passwords encoded with a MQL client of version 2021x or later.

The password can also be entered without prefix.

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

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

The Queue or Topic element may have these attributes:

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

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)

Attributes for the <Queue> element is described in the table below:

Attribute Description Note

name

The name of the queue

autoDelete

durable

exclusive

Attributes for the <Exchange> element is described in the table below:

Attribute Description Note

name

The name of the exchange

autoDelete

durable

type

The AMQP API supports providing arguments. These can be declared on the <Queue> and <Exchange> elements as shown below:

<Destinations>
    <RabbitMQ ...>
        <Queue ...>
            <Arg name="argument-name"
                 value="value of argument"
                 type="string | int | double | boolean | long | float"/>
            ...
        </Queue>
    </RabbitMQ>
</Destinations>

1.5. SOAP Destination

The SOAP destination type is used when you post data to a SOAP based webservice.

To configure such destination, the syntax is shown below:

<Destinations>
    <SOAP id="soap-1">
        <ServiceURL>http://server:8080/axis2/services/PartInfoService/update</ServiceURL>

        <Namespace prefix="part" uri="http://www.technia.com/part"/>
        <Namespace prefix="doc" uri="http://www.technia.com/document"/>
        ...

        <!-- To support basic authentication
        <Authentication>
            <UserName>A User</UserName>
            <Password>The Password</Password>
        </Authentication>
        -->

        <!-- following required for SOAP 1.1
        <ActionBaseURL>http://localhost:8080/axis2/services/</ActionBaseURL>
        <Action>PartInfoService</Action>
        <Method>update</Method>
        -->
    </SOAP>
</Destinations>

Some restrictions

  • The "ServiceURL" is mandatory.

  • Currently, you also need to specify the used XML namespaces in the payload. That is accomplished via the Namespace element.

  • The Authentication element is used to provide support for Basic authentication

  • Finally, if you call a SOAP 1.1 service, you need to specify SOAPAction header that is constructed of ActionBaseURL, Action and Method elements using format <ActionBaseURL><#><Action><:><Method>. See table below:

Element Description Note

ActionBaseURL

Base URL appended to header

Element must exist (with or without content) to include SOAPAction header

Action

Action appended (with leading # delimiter if ActionBaseURL is not empty) to header

Optional

Method

Method appended (with leading : delimiter if ActionBaseURL and/or Action is not empty) to header

Optional

To include an empty SOAPAction header, use empty element <ActionBaseURL/> and leave Action and Method unspecified.

1.6. Native MQ / Websphere MQ /IBM MQ Destination

If you must send data to a IBM MQ queue using the Native MQ protocol, then you must declare a NativeMQ destination. An exaple of so is shown below:

<Destinations>

    <NativeMQ id="mq1-partdata-req"
              queueManagerName="QM_acme_mq"
              hostName="192.168.1.10"
              port="1414"
              characterSet="1208"
              encoding="546"
              channel="S_acme_mq"
              connectOptions="">
        <Queue name="partdata_req" options="INPUT_AS_Q_DEF,OUTPUT"/>
    </NativeMQ>

</Destinations>

Attributes for the <NativeMQ> element is described in the table below:

Attribute Description Note

id

The unique identifier

queueManagerName

The name of the MQ queue manager

Required

channel

The channel to be used

Required

hostName

Required

port

The port, which your queue manager uses

Required

characterSet

Default message character set

encoding

Default message encoding

priority

Default message priority

expiracy

Default expiracy value

connectOptions

Optional additional connect options

ccsid

The <Queue> element supports these attributes:

  • name : The name of the queue

  • options Comma separated list of MQOO option (MQ Open Options)

    Example: INPUT_AS_Q_DEF,OUTPUT

1.7. Email destination

An email destination is used to send data to one or more email recipients. Below is an example configuration.

<Destinations>

    <Email id="email-1" subject="My Test Message">
        <To>example1@technia.com</To>
        <To>example2@technia.com</To>
        <Cc>example3@technia.com</Cc>
        <Bcc>example4@technia.com</Bcc>
    </Email>

</Destinations>

The table below describes the available attributes for element Email.

Attribute Description Required

id

A unique identifier.

Yes

subject

The "Subject" header field of message.

No

The table below describes the available sub elements for element Email.

Element Description Required

To

The "To" (primary) recipient. At least one must be defined.

Yes

Cc

The "Cc" (carbon copy) recipient. One or more can be defined.

No

Bcc

The "Bcc" (blind carbon copy) recipient. One or more can be defined.

No

Mail Settings

Mail settings must be configured to enable email destination. See chapter [Configure Mail Settings].

1.8. FTP destination

An FTP destination is used to send data to a file located in an FTP(S) server. Below is an example configuration.

<Destinations>

    <FTP id="ftp-1"
        hostName="myHost"
        port="21"
        userName="myUserName"
        password="myPassword"
        directory="myDir/mySubDir"
        filePrefix="myPrefix-"
        fileSuffix=".xml"
        existStrategy="replace"
        useSSL="false"
        implicit="false"
        usePROTP="true" />

</Destinations>

The table below describes the available attributes for element FTP.

Attribute Description Required Default Value

id

A unique identifier.

Yes

hostName

Host name of a FTP(S) server.

Yes

port

Port number of the server. Default one is used if not defined.

No

userName

Name of a user that is logged in.

No

password

User’s password.

No

directory

A directory to which the file is uploaded. If not defined, default working directory is used.

No

fileName

A static name for the uploaded file. If defined, filePrefix and fileSuffix are omitted.

No

filePrefix

A prefix which the uploaded file will get. If fileName is defined, this is omitted.

No

fileSuffix

A suffix which the uploaded file will get. If fileName is defined, this is omitted.

No

existStrategy

Defines what happens if a file with fileName already exist in the working directory.

You may use the following values:

append

Appends the data in the of existing file.

replace

Replaces the existing file.

fail

Causes the transfer to fail.

No

fail

useSSL

Defines if an SSL connection is used to communicate with the FTP Server.

Use value "true" or "false".

No

false

implicit

Defines if implicit security mode is used.

Use value "true" to enable implicit mode or "false" for explicit mode.

If useSSL is not enabled, this option is omitted.

No

false

usePROTP

Defines if command "PROT P" is executed in the server. This means private security mode is used.

Use value "true" or "false".

If useSSL is not enabled, this option is omitted.

No

false

Either fileName or filePrefix is required. If fileName is not defined, the name of uploaded file will consist of filePrefix, a random string and optional fileSuffix.
TLS session presumption is not supported when PROT P (usePROTP) is used.

1.9. Handling Delivery Failures

If a delivery fails to some destination, you can configure an error handler per each destination.

To do so, use the XML format as shown below: (Example used for RabbitMQ, but applies to all destination types).

<Destinations>
    <RabbitMQ ...>
        <OnError> (1)
            <SendMail>
               <Subject>Unable to use RabbitMQ destination</Subject>
               <TO>support@company.com</TO>
               <TO>another@company.com</TO>
               <CC>tif.admin@company.com</CC>
               <ContentType>text/plain</ContentType>
               <Message>
                  An error occured. Error message was: ${ERROR_MESSAGE} (2)

                  Pls look at the stack trace below.
                  ${STACK_TRACE} (2)
               </Message>
            </SendMail>
        </OnError>
    </RabbitMQ>
</Destinations>
1 The <OnError> element is supported on all destinations.
2 The macros ERROR_MESSAGE and STACK_TRACE refers to the exception raised during the use of the destination.

An alternative approach is to implement a custom ErrorHandler

<Destinations>
    <RabbitMQ ...>
        <OnError>
            <Handler>name of class</Handler> (1)
        </OnError>
    </RabbitMQ>
</Destinations>
1 The class specified here must implement com.technia.tif.core.error.ErrorHandler