23 August 2013

1. Configuration Files

TIF allows a great amount of possibilities to configure your integration use cases instead of directly having to write Java code. This is accomplished by using XML definitions (or XML configurations) that contains the configuration details. In some cases, other kind of configuration files than XML files are used such as script files.

TIF is built upon the TVC (Technia Value Components) software and hence utilizes the resource/configuration loading capabilities provided by TVC Core. If you are familiar using TVC together with your ENOVIA™ web-application, you might already be aware of how to use these XML configurations.

Below is a list showing some commonly used XML configuration types within TIF.

jobcfg

XML files describing a job e.g. job configuration

payload

XML files defining how to create the payload data e.g. payload definition.

xsd

XML schema files used for validation of XML data, for example when validating the generated payload data being sent to some destination.

xslt

XSLT files used to transform XML files into different formats.

table

XML files defining tables that are being used when extracting data from ENOVIA

tablecolumn

Columns used across several tables can be placed in its own files in order to encourage reuse.

dataset

XML files defining data-sets that defines what data to be included in the creation of the payload.

createconfig

Configuration for the Create/Update integration.

soapservice

Definition of a configurable SOAP service.

restservice

Definition of a configurable REST service

script

Script files containing script code being executed by the JVM.

template

Template files used for generating payload. E.g Apache Freemarker templates

xmlspec

XML Specification used to adapt the generated/raw XML as generated from the Java objects. The XML spec allows you to produce XML data that requires less transformation rules than otherwise is needed.

directorylistener

Defines a directory/file listener used for performing actions on files

jmslistener

Defines a JMS listener used for receiving messages from a JMS broker.

rabbitmqlistener

Defines a Rabbit MQ listener used for receiving messages from a Rabbit MQ broker.

mqlistener

Defines an IBM MQ listener that will receive messages from a MQ broker.

replyhandler

Defines a handler being responsible for handling asynchronous replies. E.g responses to messages produced by an outbound integration job, typically messages obtained from a message broker or similar.

1.1. Naming

When referring to an XML based definition, one has to follow a special naming convention in order for TIF/TVC to recognize such a resource.

For example, if you somewhere in TIF wants to refer to a table that is defined in an XML file (and not a system table defined in the database), you may use the following naming convention to point to such resource:

tvc:table/EBOM.xml

1.2. Domains or Namespaces

It is also possible (and recommended) to use separate domains/namespaces for the resources. For example resources belonging to one domain of an application can be kept completely separate from another domain of an application. This is illustrated below:

tvc:table:sapintegration/EBOM.xml
tvc:dataset:sapintegration/EBOMStructure.xml

In the example above we are referring to a table and a dataset stored in the namespace "sapintegration".

The number of configuration files tend to grow over time, and the domain/namespace concept allows arranging the configurations in relevance to a particular functionality or usecase.

If you refer to a configuration file living in the "default" domain, you can in many cases omit the "tvc:<type>" prefix and only use the file name.

1.3. Accessing an XML Based Resource

The table below illustrates how to correctly write the name of an XML based resource.

Resource Type Name Prefix

Table

tvc:table/MyTable.xml

Table Column

tvc:tablecolumn/MyColumn.xml

Payload

tvc:payload/PayloadExample.xml

XSLT

tvc:xslt/MyStylesheet.xslt

When using domains, you have to apply the domain name after the resource type. For example:

tvc:table:mydomain/MyTable.xml
It is not recommended to use a domain name, which is used for to represent a resource type. For example, you should not have a domain called "table", "payload", "dataset" etc.

1.4. Location of Resource Files

The XML configuration files that are being used in many use cases in TIF are stored in the cfg folder under ${TIF_ROOT}/modules/enovia. TIF uses the resource loading mechanism from TVC Core to resolve configuration files from this folder.

In versions prior to 2016.2, the name of this directory was tvc-cfg. If this directory is present it will be added for convenience, however in some cases this may not work - especially for SOAP services defined in the "soapservice" directory due to limitations in the Axis2 deployer.

If you are used to working with TVC in your ENOVIA application, the cfg folder corresponds to the WEB-INF/tvc folder.

The supported XML configuration types are the same as available in TVC with some additional configuration types provided by TIF, such as job-configurations, payload definitions, configurable web-services and others.

Once an XML resource is requested, the name of the resource is translated into a path, which points to the actual resource file. The list below shows the path for each resource type.

The translation of name to the actual file is:

${TIF_ROOT}/modules/enovia/cfg/${RESOURCETYPE}/${FILENAME}
Resource Type Location

Table

${TIF_ROOT}/modules/enovia/cfg/table

Table Column

${TIF_ROOT}/modules/enovia/cfg/tablecolumn

Payload

${TIF_ROOT}/modules/enovia/cfg/payload

XSLT

${TIF_ROOT}/modules/enovia/cfg/xslt

When the resource refers to a resource under a specific domain, the name is translated according to the following rules:

${TIF_ROOT}/modules/enovia/cfg/${DOMAIN}/${RESOURCETYPE}/${FILENAME}

Below is a table showing some examples of paths translated

Resource Type Location

Table

${TIF_ROOT}/modules/enovia/cfg/${DOMAIN}/table

Table Column

${TIF_ROOT}/modules/enovia/cfg/${DOMAIN}/tablecolumn

Payload

${TIF_ROOT}/modules/enovia/cfg/${DOMAIN}/payload

1.5. Configure Additional Configuration Directory

As mentioned in the previous chapter, configuration files are typically stored within ${TIF_ROOT}/modules/enovia/cfg. Also, if your TIF start script points out the WEBAPP_ROOT_DIR, then the WEB-INF/tvc-ext and WEB-INF/tvc folders also will be added to the resource loader path.

In addition to this, there is also a Java system property called extraConfigDirectory that you could use to point out a custom directory, from where additional configurations can be resolved. If this property is present, the directory that is pointed out will be added first to the resource loader path.

In the Start script for TIF you could apply it like below:

export START_ARGS=-DextraConfigDirectory=/home/user/repos/test/cfg
...

There are also some other properties (defined in module.properties) that you can use to control how the configuration files are being resolved.

Name Description

configDirectory.webapp.enabled

Can be used to disable loading configuration files from the webapplications WEB-INF/tvc folder (in case you reference the Web-app root dir in the start of TIF).

configDirectory.default.enabled

Can be used to disable loading configurations from the default "cfg" folder.

1.6. XML Schemas

For most of the configuration files, there are XML schema files available for validation. These files will both be provided as a part of the TIF distribution and also available online.

The schema files are located under ${TIF_ROOT}/modules/enovia/schema

Type Local Schema File Remote URL Namespace

jobcfg

${TIF_ROOT}/modules/enovia/schema/JobCfg.xsd

payload

${TIF_ROOT}/modules/enovia/schema/Payload.xsd

createconfig

${TIF_ROOT}/modules/enovia/schema/CreateConfig.xsd

replyhandler

${TIF_ROOT}/modules/enovia/schema/ReplyHandler.xsd

restservice

${TIF_ROOT}/modules/enovia/schema/RESTService.xsd

soapservice

${TIF_ROOT}/modules/enovia/schema/SOAPService.xsd

xmlspec

${TIF_ROOT}/modules/enovia/schema/XMLSpec.xsd

table

-

tablecolumn

-

dataset

-

directorylistener

${TIF_ROOT}/modules/enovia/schema/DirectoryListener.xsd

jmslistener

${TIF_ROOT}/modules/enovia/schema/JMSListener.xsd

amqplistener

${TIF_ROOT}/modules/enovia/schema/AMQPListener.xsd

mqlistener

${TIF_ROOT}/modules/enovia/schema/MQListener.xsd

Example how to reference an XML schema from a configuration file:

<?xml version="1.0"?>
<tif:Job
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:tif="http://technia.com/TIF/JobCfg"
    xmlns:common="http://technia.com/TIF/Common"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://technia.com/TIF/JobCfg http://products.technia.com/tif/schema/latest/JobCfg.xsd">
</tif:Job>

1.7. Reloading of XML based resources

When a resource file is changed, for example a table is updated; TIF/TVC will (if TIF/TVC is started in development mode) reload the resource automatically, this is done by checking the modified timestamp on the file.

If TIF/TVC is started in PRODUCTION mode, you will need to clear the TVC cache in order to reflect the new changes, which could be done by connecting a JMX client to the JVM running TIF (there is a MBean available from TVC to clear the cache).

E.g. there is no need to restart the TIF server.

1.8. Special Configurations - Service Activators

Some configuration types in TIF corresponds to more complex deployment inside TIF. The configurations in question are listed below.

  • Directory Listener

  • JMS Listener

  • MQ Listener

  • AMQP Listener

  • Reply Handler

Instances of these configuration types are represented as service activators internally in TIF. They represent manageable functionality that can be started/stopped individually.

1.8.1. Hot Deployment of Service Activators

TIF allows hot deploying such configuration, meaning that creating, modifying or deleting such resource can be handled at runtime. Earlier in TIF, you had to restart the TIF server to handle changes in these configurations.

If you add a configuration of such type, a new service activator will be created and made available in TIF.

Same if you remove a configuration of this type, the corresponding service activator will be stopped and removed.

Changing a configuration of this type will, if the service activator is running, cause the service activator to restart with the configuration changes reflected in the service activator.

This feature is per default enabled but can be disabled via a setting in ${TIF_ROOT}/modules/enovia/etc/module.custom.properties.

configChangeListener.enabled = false

1.9. Working with Resources Stored on the Classpath

A resource can also be stored within the classpath (i.e. in a JAR file). To refer to such a resource, for example under /com/acme/resources/MyTable.xml, you have to write the name as:

tvc:table//com/acme/resources/MyTable.xml

If you want to override the definition of the resource found in the classpath, you can then create a new file called MyTable.xml under the following directory:

${TIF_ROOT}/modules/enovia/cfg/table/com/acme/resources/MyTable.xml

The internal resource handler in TVC will first look into such a directory and check if the resource exists there before retrieving it from the classpath.

1.10. Dataset Definition

Please goto this page.

1.11. Table Definition

Please goto this page.

1.12. Payload Definition

Please goto this page.