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
-
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 to transfer the data to an IBM-MQ broker via the Native-MQ protocol. Note that IBM MQ also supports the JMS protocol.
- Kafka
-
Transfer data to an Apache Kafka topic
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>
TIF generally do not bundle any vendor specific JAR files. You need to manually decide which vendor JAR files that are required, and put these into the folder |
Passwords in the Destinations File
To avoid storing passwords in clear text in the destination file, one can in most places where a password is declared encode it in a few different ways.
See more this document how to encode passwords.
Instance Specific Files
If you run multiple TIF instances, you may in some cases need to have instance / node specific destinations file. This is supported, and the order how the destinations.xml files are parsed is shown below.
-
etc/destinations.xml
-
etc/destinations-<TIF-INSTANCE-ID>.xml
-
etc/destinations-<TIF-NODE-ID>.xml
-
etc/destinations-<TIF-NODE-ID>-<TIF-INSTANCE-ID>.xml
This means that you could override the configuration of a destination by putting them in one of the files that is being parsed latest.
Token Resolver
Some destinations, like the Http destination, may require some additional tokens to be established prior to performing the actual http reqeust. To support that, you can register token resolvers within the destinations file.
<Destinations>
<TokenResolver id="keycloak" cacheFor="300s">
...
</TokenResolver>
</Destinations>
You can define as many token resolvers as needed, just ensure that each have a unique identifier.
The cacheFor
directive specifies the duration how long the generated tokens may be reused.
The tokens are cached per url/header/payload combination, meaning that if your token resolver
uses dynamic values, the caching is sensitive to the resolved values and thus each token resolver may contain many cache entries.
Configuration Format
On a high level, the token resolver configuration contains three parts:
- Request
-
Defines how the request will be constructed when requesting the tokens. There is support for constructing requests using either x-www-form-url-encoded key/value pairs or JSON request bodies.
- Response
-
Defines what data from the response we are interested in when contructing our tokens. Currently you can take values from response headers and/or JSON values from the response body.
- Tokens
-
Specifies the tokens to be used and how to build these.
Below is a complete example for a token resolver that works against Keycloak to establish an authorization token according to the OAuth2 client credentials flow.
<Destinations>
<TokenResolver id="keycloak-1" cacheFor="5m">
<Request url="http://localhost:30180/auth/realms/${job.param.keycloak_realm}/protocol/openid-connect/token">
<Params>
<Param name="grant_type" value="client_credentials" />
<Param name="scope" value="${job.param.keycloak.scopes}" />
<Param name="client_id" value="tif" />
<Param name="client_secret" value="${tif.setting.keycloak.tif.secret}" />
</Params>
</Request>
<Response>
<Json>
<Map jsonPath="$.access_token" as="access_token" />
<Map jsonPath="$.token_type" as="token_type" />
</Json>
</Response>
<Tokens>
<Token name="Authorization" macro="${token_type} ${access_token}" />
</Tokens>
</TokenResolver>
<Http id="http-dest-with-keycloak" tokenResolver="keycloak-1" url="..." />
</Destinations>
In this example, the request is a param name/value request and the response is of type JSON.
It is also possible to send out JSON data and map the response headers into tokens, see example below:
<TokenResolver id="monitor" cacheFor="24H">
<Request
url="http://monitor:8001/${tif.setting.monitorLanguageCode}/${job.param.companyNumber}/login">
<Json> <!-- implies application/json + method = POST -->
<Object>
<Property name="Username" string="${job.param.monitorUserName}" />
<Property name="Password" string="${job.param.monitorPassword}" />
<Property name="ForceRelogin" bool="true" />
</Object>
</Json>
</Request>
<Response>
<Header name="X-Monitor-SessionId" as="sessionId" />
</Response>
<Tokens>
<Token name="X-Monitor-SessionId" value="${sessionId}" />
</Tokens>
</TokenResolver>
The details of each element is described below.
<TokenResolver>
The top level element <TokenResolver>
supports the following attributes.
Attribute | Description | Required |
---|---|---|
id |
A unique identifier among all token resolvers. |
Yes |
cacheFor |
An optional duration definition specifying how long time the token may be cached. If omitted, no caching takes place. Example values:
|
No |
Supported child elements:
-
<Request>
-
<Response>
-
<Tokens>
<Request>
Specifies how the request will be constructed.
This element supports the following attributes
Attribute | Description | Required |
---|---|---|
url |
The URL to perform the request against |
Yes |
method |
Specifies request method. If omitted, GET is used in case no body is configured and POST is used if a body is configured. |
No |
contentEncoding |
Can be used to control the content encoding. Default is UTF-8 |
No |
proxyOverride |
Can be used to override global proxy settings in TIF |
No |
disableProxy |
Can be used to disable using proxy server for token resolving. |
No |
The request will per default use the global http/https proxy setting unless overridden via the See this document for details around proxy settings in TIF. |
Supported child elements:
Element | Description | Required |
---|---|---|
|
Defines that you will send JSON data to the server. |
No |
|
Defines that you will send key/value parameters |
No |
|
Defines additional headers to be part of the request |
No |
<Json>
The Json element is used to declare a JSON structure to be generated
See example below how to construct such Json definition:
<Request ...>
<Json>
<Object>
<Property name="Username" string="${job.param.monitorUserName}" />
<Property name="Password" string="${job.param.monitorPassword}" />
<Property name="ForceRelogin" bool="true" />
<Array name="test">
<Property int="1" />
<Property int="2" />
</Array>
</Object>
</Json>
</Request>
This will generate a JSON payload like the example below:
{
"Username" : "the resolved value from the job param monitorUserName",
"Password" : "the resolved value from the job param monitorPassword",
"ForceRelogin" : true,
"test" : [ 1, 2 ]
}
You can use <Object>
, <Array>
and <Property>
to define the structure.
The Property element supports the following attributes:
Attribute | Description |
---|---|
string |
Defines that the value is of type string |
bool |
Defines that the value is of type boolean |
int |
Defines that the value is of type int64 |
double |
Defines that the value is of type double |
number |
Defines that the value is of type number |
splitValueBy |
Specify optional separator that can be used to split the value into an array instead |
<Params>
The <Params>
element is used to define a payload that is x-www-form-urlencoded (e.g. a form post).
Example:
<Request ...>
<Params>
<Param name="grant_type" value="client_credentials" />
<Param name="scope" value="${job.param.keycloak.scopes}" />
<Param name="test" value="a,b,c,d" splitBy="," />
</Params>
</Request>
This will generate a payload like below
grant_type=client_credentials&scope=s1+s2+s3+s4&test=a&test=b&test=c&test=d
The <Params>
element contains one or more <Param>
elements, which supports the following attributes.
Attribute | Description | Required |
---|---|---|
name |
Name of parameter |
Yes |
value |
The value of the parameter |
Yes |
splitValueBy |
Specify optional separator that can be used to split the value into an array instead |
No |
<Response>
The <Response>
element defines what data you are interested in from the response.
You can save values from headers and/or data from a JSON response body.
The idea is that you will define what data you are interested in and associate that with a variable. Later on, you will use those variables to construct the final tokens.
When working with JSON response data you will use so called JSON paths to select data from the JSON structure to be saved.
For more detailed information about JSON path, see this document
Below is an example where the properties token_type and access_token are saved from the JSON object. Note that selecting anything else than plain literals (strings, numbers, booleans) are typically not supported.
<Response>
<Json>
<Map jsonPath="$.token_type" as="tokenType" />
<Map jsonPath="$.access_token" as="accessToken" />
</Json>
</Response>
The <Map>
element supports the following attributes
Attribute | Description | Required |
---|---|---|
jsonPath |
The JSON path expression to use |
Yes |
as |
The name of the variable to save the value as |
Yes |
To save some header values into a named variable, see the example below:
<Response>
<Header name="X-Monitor-SessionId" as="sessionId" />
<Header name="Another-Header" as="another" />
</Response>
The <Header>
element supports the following attributes
Attribute | Description | Required |
---|---|---|
name |
Name of header to take |
Yes |
as |
The name of the variable to save the value as |
Yes |
ignoreCase |
If header names are case sensitive or not. Default is to ignore case. |
No |
<Tokens>
The final tokens to use are defined within the <Tokens>
element.
See example below where the Authorization token is generated based upon the variables token_type
and access_token
<TokenResolver>
...
<Tokens>
<Token name="Authorization" macro="${token_type} ${access_token}" />
</Tokens>
</TokenResolver>
The <Token>
element supports the following attributes
Attribute | Description | Required |
---|---|---|
name |
Name of the token |
Yes |
macro |
The macro to use when resolving the token value |
Yes |
value |
The fallback value to use |
No |
File Destination
A file destination is used to define a location where files are either written to or read from.
Below is an example configuration 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:
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.
|
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 |
tokenResolver |
The ID of the token resolver to be used to establish additional authentication tokens |
No |
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>
</Destinations>
1 | Defines the authentication block |
2 | Either Basic or Digest can be used |
3 | Specifies username |
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/3DEXPERIENCE MQL command "encrypt password". If an 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>
</Destinations>
See more this document how to encode passwords.
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.
Preempt Basic Authentication
Unless configured differently, when using Basic authentication the authorization header is sent preemptive per default. E.g. it is sent with the initial request. NOTE: this behavior was changed as of release 2024.1.0, earlier releases had false as default behavior for preemptive authorization challenge.
You can configure a HTTP destination with authentication to not do this. E.g. when transferring data to a HTTP destination for the first time, the HTTP client wihtin TIF could use 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.
To explicitly configure the preemptive mode, use the configuration attribute as shown below
<Destinations>
<Http id="http-1" >
<Authentication preempt="true | false">
...
</Authentication>
</Http>
</Destinations>
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 |
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 |
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 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>
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"
.
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>
</Destinations>
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>
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. |
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
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]. |
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, |
No |
|
filePrefix |
A prefix which the uploaded file will get. If |
No |
|
fileSuffix |
A suffix which the uploaded file will get. If |
No |
|
existStrategy |
Defines what happens if a file with You may use the following values:
|
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 |
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 |
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.
|
Kafka Destination
A Kafka destination is used to send data to a Kafka topic.
Example configuration:
<Destinations>
<Kafka id="kafka-test-1"
bootstrapServer="server1:9092,server2:9092,server3:9092"
acks="all"
linger="5"
clientId="${tif.node}_${tif.instance}"
topic="test-1">
<ProducerProperty name="" value="" />
</Kafka>
</Destinations>
The table below describes the available attributes for element Kafka.
Attribute | Description | Consumer / Producer | Required | Default Value |
---|---|---|---|---|
id |
A unique identifier. |
Both |
Yes |
|
bootstrapServer |
Comma separated list of Kafka bootstrap server(s) |
Both |
Yes |
|
clientId |
Define a string used to identify the client. Can include macros |
Both |
No |
|
acks |
Define the acks value |
P |
No |
1 |
linger |
Define the Kafka linger in MS |
P |
No |
0 |
topic |
Defines a default topic to be used when using this destination. |
Both |
No |
|
groupId |
Defines what consumer group to join |
C |
No |
In addition, you can also:
-
Add custom producer properties via nested
<ProducerProperty>
elements. -
Add custom consumer properties via nested
<ConsumerProperty>
elements. -
Define custom headers to be sent when producing data via nested
<Header>
elements
The nested <ProducerProperty>
, <ConsumerProperty>
and <Header>
elements uses the attributes name
and value
.
Per default, TIF will produce data to a Kafka topic using a string encoder for the keys and a byte-array encoder for the values. When TIF consumes data from Kafka, it will deserialize both the keys and values using a String decoder. |
Below is an example when using Kafka with authentication:
<Kafka id="kafka-test-1"
bootstrapServer="server1:9092,server2:9092,server3:9092"
acks="all"
linger="5"
clientId="{{ tif_client_id }}"
topic="{{ kafka_topic }}">
<ProducerProperty name="security.protocol" value="SASL_SSL" />
<ProducerProperty name="sasl.mechanism" value="OAUTHBEARER" />
<ProducerProperty name="sasl.login.callback.handler.class" value="org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler" />
<ProducerProperty name="sasl.oauthbearer.token.endpoint.url" value="https://aws.test.com/auth/realms/protocol/openid-connect/token"/>
<ProducerProperty name="sasl.jaas.config" value="org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required clientId="{{ tif_client_id }}" clientSecret="{{ tif_client_secret }}";" />
</Kafka>
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 |