TIF ENOVIA/3DExperience Connector - 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/3DEXPERIENCE 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/3DEXPERIENCE
- 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.
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
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. |
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. |
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/3DEXPERIENCE 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 |
|
Table Column |
|
Payload |
|
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 |
|
Table Column |
|
Payload |
|
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. |
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 |
|
||
payload |
|
||
createconfig |
|
||
replyhandler |
|
||
restservice |
|
||
soapservice |
|
||
xmlspec |
|
||
table |
- |
||
tablecolumn |
- |
||
dataset |
- |
||
directorylistener |
|
||
jmslistener |
|
||
amqplistener |
|
||
mqlistener |
|
||
kafkalistener |
|
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>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.
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
-
Kafka 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.
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 = falseWorking 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.xmlIf 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.xmlThe 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.
Dataset Definition
Please goto this page.
Table Definition
Please goto this page.
Payload Definition
Please goto this page.