enovia.host = http://server:8001/internal
15 January 2016
© Copyright 2003-2020 by TECHNIA AB
All rights reserved.
PROPRIETARY RIGHTS NOTICE: This documentation is proprietary property of TECHNIA AB. In accordance with the terms and conditions of the Software License Agreement between the Customer and TECHNIA AB, the Customer is allowed to print as many copies as necessary of documentation copyrighted by TECHNIA relating to the software being used. This documentation shall be treated as confidential information and should be used only by employees or contractors with the Customer in accordance with the Agreement.
This product includes software developed by the Apache Software Foundation. (http://www.apache.org/).
The ENOVIA connector is a module within TIF that knows about ENOVIA™ and how to connect to the ENOVIA™ database.
The ENOVIA™ connector is installed below the ${TIF_ROOT}/modules/enovia
folder, from now on referred to as the module home directory.
Please also read the chapter "Installation Overview" in this document in order to understand the different connection alternatives. In case you dont connect with ENOVIA in RIP mode (the default mode), then you need to configure the enovia host connection within the "tvc.custom.properties" file (see chapter below).
enovia.host = http://server:8001/internal
Within the enovia module directory, you will have a number of sub-directories:
Contains for example
The properties file controlling the behavior of this module
The properties file used when initializing TVC.
Note that the ENOVIA Connector is built upon the TVC-Core framework. (TVC =Technia Value Components)
Configuration file for scheduled jobs.
The JAR files required by the ENOVIA connector.
Custom jar files are stored in a subfolder of the lib
folder.
Holds the configuration files. Mainly XML configuration files, but others like XSLT/Freemarker templates/XML Schemas are also located here) that you are using inside your integration jobs.
Might for example be job-configurations, payload definitions, data-sets, tables, inquiries etc.
This directory contains the similar file as you use in the ordinary ENOVIA web-application below the WEB-INF/tvc
folder (in case you are using TVC as a part of your ENOVIA™ application).
Contains custom web-applications, which this module has. By default, there are a couple of applications available like the administration UI, RESTful Webservice support and SOAP based Webservice support.
Never modify the original properties files that are part of the distribution. For example instead of changing the The customized properties file is propagated with the original file upon start up, and the customized file takes precedence over the original. |
Your integrations requires the same JAR files as you have in your ENOVIA application, such as the eMatrixServletRMI.jar
among others. Hence these JAR files must be available for the ENOVIA Connector in TIF in order to work correctly.
There are two options how to ensure that TIF uses these JAR files, namely:
In the start script to TIF, point out the root directory of your ENOVIA web-application. TIF will during start up scan the directories WEB-INF/classes
and WEB-INF/lib
and include the resources in the class-path automatically.
Copy required JARs from the WEB-INF/lib
and WEB-INF/classes
into the lib/custom
folder.
The minimum required JAR files are:
eMatrixServletRMI.jar
enoviaKernel.jar
FcsClient.jar
FcsClientLargeFile.jar
Mx_jdom.jar
The first alternative is the recommended approach since that reduces the risk of not having the content synchronized between the app-server and the TIF server.
If you for some reason cannot link directly to your ENOVIA web-application root directory, you can possibly copy the whole application to some place on the TIF server.
Never add your own JAR files into the |
If you need to change or apply some TVC specific setting (init parameter), then
you can do so by creating a file called tvc.custom.properties
within the directory ${TIF_ROOT}/modules/enovia/etc
.
In there you add the parameters using property file format (key = value).
Before reading this, ensure that you also read this chapter. |
If you wish to configure things different per TIF instance, you should create a file
called ${TIF_ROOT}/modules/enovia/etc/${INSTANCE_ID}.properties
and add the instance specific
configuration in there.
The order the properties files are read is:
${TIF_ROOT}/modules/enovia/etc/module.properties
${TIF_ROOT}/modules/enovia/etc/module.custom.properties
${TIF_ROOT}/modules/enovia/etc/${INSTANCE_ID}.properties
When setting up multiple instances of TIF you should consider for example if all instances should poll the default queue in ENOVIA for new jobs, or if all instances should listen to the same JMS/MQ/AMQP queues.
Also see the this chapter for additional information about reply handlers and use of JMS correlation id’s and IBM-MQ group id’s.
The settings for the ENOVIA Connector in TIF is found inside the file ${TIF_ROOT}/modules/enovia/etc/module.properties
.
If you want to change or add something in this file, create an empty
file with name module.custom.properties in the same directory.
All your changes should go into the customized file.
|
Note also that you may apply instance specific properties. This may be important in case you have multiple TIF instances running and you need to configure the instances slightly different.
Read here for more details.
In order to be able to connect to ENOVIA/3DExperience with the Java API, you
need some JAR files from the ENOVIA/3DX installation. One way to do this is to
set the WEBAPP_ROOT
environment variable pointing to the root of your ENOVIA
web application when starting up TIF. Typically this is done within the
${TIF_HOME}/bin/setenv.sh
script or similar.
Note that some JAR files that you might have in the web application you point out, may contain JAR files that is in conflict with what TIF is using. Hence, you need to be able to control what to include/exclude.
The following properties are used to control this.
include.jar.file.pattern.defaults
include.jar.file.pattern
exclude.jar.file.pattern.defaults
exclude.jar.file.pattern
The properties ending with .defaults
contains a pre-defined list of JAR files to
either include or exclude provided by TIF. Generally, you should not override
or modify these properties.
Instead, to control what to be excluded OR included, use these properties within your custom configuration file.
include.jar.file.pattern
exclude.jar.file.pattern
Both of these properties contains a ;
separated list of regular expressions
that are matched on the files in the web application (the lib directory).
As of version 2020.1.0, a more restrictive strategy was introduced (the include pattern) due to increasing number of support tickets caused by including too many conflicting JAR files in TIF. |
Per default, TIF provides both a list of JARs to be included and a list of JARs to be excluded. And these are defined as follows:
exclude.jar.file.pattern.defaults=mx_axis.jar;\
slf4j-.*\.jar;\
logback-classic.jar;\
logback-core.jar;\
profiler-server.jar;\
tvc-collaboration-.*\.jar;\
tif-enovia-client-.*.jar;\
jsf-.*\.jar;\
jstl-.*\.jar;\
ehcache-.*\.jar;\
enoappmvc.jar;\
fasterxml-jackson.*.jar;\
jackson-.*.jar;\
javax.*.jar;\
.*rest.*.jar
exclude.jar.file.pattern=
include.jar.file.pattern.defaults=eMatrixServletRMI.jar;\
enoviaKernel.jar;\
FcsClient.jar;\
FcsClientLargeFile.jar;\
Mx_jdom.jar;\
search_common.jar
include.jar.file.pattern=
Moreover, you can disable a pattern completely by using any of these properties
include.jar.file.pattern.enabled=true
exclude.jar.file.pattern.enabled=true
So to revert back to pre-2020.1.0 behaviour, you can simply add this into your custom property file.
include.jar.file.pattern.enabled=true
There is support for HTTP inside TIF, for example running Webservices etc.
You may disable HTTP, or make configuration changes such as changing context paths. All of this is defined in the module.settings file.
You can configure TIF to integrate with Elasticsearch in order to enhance the usage of the Admin UI.
This in turn will also reduce the load on the TIF server since some queries from the Admin UI adds a lot of work to the TIF server. E.g. CPU/memory can be used for job processing instead of running expensive Admin UI queries.
You need to install Elasticsearch as a separate service. We have tested TIF with versions 6.2 up-to 7.1 of Elasticsearch.
After setup of the Elasticsearch server, you need to configure some properties on the TIF side.
searchIndexer=elasticsearch
elasticSearch.hosts=http://name-of-host:9200
There are plenty of other properties that plays a role, but by default you don’t need to deal with them.
You can read more about these properties within the module.properties
file.
If you have multiple TIF instances in your production system, all of these should use the same Elasticsearch instance. TIF separates the data within the index by the tif-node-id AND tif-instance-id. But, don’t use the same Elasticsearch index for TEST instances as you use for your PRODUCTION instances. |
TIF has a routine for adding legacy data not yet being indexed, to the index by a Search Index Synchronizer.
If your database contains large amount of jobs and payload data, it may take some time to completely add all data into the index. The data is added to the index in chunks in order to not make the TIF server unresponsive. |
There is a background task running on the TIF server that takes care about this.
This task is configured by default like this:
searchIndexer.synchronizer.execute=0 0/5 * * * ?
searchIndexer.synchronizer.job.chunkSize=2000
searchIndexer.synchronizer.job.maxIterations=100
searchIndexer.synchronizer.payload.chunkSize=300
searchIndexer.synchronizer.payload.maxIterations=100
E.g. every fifth minute, look for un-indexed data. On each run, run maximum 100 iterations and on each iteration try to index max 2000 jobs.
You may need to elaborate on these settings to your environment. It may also be wise to use different values during the initial period when all legacy data is being added to the index, and later change to run this routine less often.
The payload data will be added to the index AFTER all jobs have been added.
The chunk size for payload may need to be changed depending on typical/average size of your payload data. |
If either chunk size or max iterations is set to a negative value, then no synchronization will be made for that type.
Un-indexed data is either job-data being created in the past OR job-data that is created during a period when TIF does not have contact with your Elasticsearch server.
Clean-up routine for old scheduled job executions is performed by scheduled job "tidy-routine-for-scheduled-job-executions" under group "tif-internal-maintenance-jobs".
By default, the clean-up runs once per hour and keeps 20 newest execution entries in the log history.
The settings can be configured in ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
Defaults are as follows:
scheduledJobCleanser.enabled=true
scheduledJobCleanser.execute=0 0 0-23 * * ?
scheduledJobCleanser.keepCount=20
How the class loading mechanism in TIF is working is important to understand if you will add customized code into TIF.
Below is a diagram showing the hierarchy:
The top level class loader contains the classes found from JAR files inside ${TIF_ROOT}/lib
. These classes are visible for all modules in TIF.
The ENOVIA™ connector has it’s own class loader, with the TIF core class loader as parent. This class loader loads classes from the lib
and lib/custom
directories of that module by default as well as (if configured via start-script) the web-application resources (WEB-INF/lib, WEB-INF/classes).
Within the ENOVIA™ connector, there exists web-applications supporting SOAP, REST and Apache CXF based web services. Each of these is placed in a separate web-app using their own class loader. The folders WEB-INF/classes
and WEB-INF/lib
beneath each webapp is then part of the classpath.
The table below explains where to place custom classes:
Folder | What to place |
---|---|
|
Custom classes related to TIF core, such as custom destinations. |
|
Custom classes that customize behavior of ENOVIA connector related actions. |
|
Custom classes related to REST based web services |
|
Custom classes related to SOAP based web services |
|
Custom classes related to Apache CXF based web services |
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.
XML files describing a job e.g. job configuration
XML files defining how to create the payload data e.g. payload definition.
XML schema files used for validation of XML data, for example when validating the generated payload data being sent to some destination.
XSLT files used to transform XML files into different formats.
XML files defining tables that are being used when extracting data from ENOVIA
Columns used across several tables can be placed in its own files in order to encourage reuse.
XML files defining data-sets that defines what data to be included in the creation of the payload.
Configuration for the Create/Update integration.
Definition of a configurable SOAP service.
Definition of a configurable REST service
Script files containing script code being executed by the JVM.
Template files used for generating payload. E.g Apache Freemarker templates
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.
Defines a directory/file listener used for performing actions on files
Defines a JMS listener used for receiving messages from a JMS broker.
Defines a Rabbit MQ listener used for receiving messages from a Rabbit MQ broker.
Defines an IBM MQ listener that will receive messages from a MQ broker.
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.
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
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. |
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. |
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 |
|
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 |
|
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. |
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 |
|
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>
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.
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.
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
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.
Please goto this page.
Please goto this page.
Please goto this page.
Jobs executed on the TIF server may be initiated through some event within the ENOVIA™ web-application (or thick/rich client). You may for example configure a trigger that will initiate a job (for example promote event, create event etc.).
The kind of jobs that most typical is initiated in this way are Outbound Integration Jobs and/or Batch Jobs.
When this happens, then within the ENOVIA™ database a business object of type "TIF Job" in a separate vault dedicated to TIF is created. This job object holds the necessary information for the later execution of the Job on the TIF side. The Job object is then connected to a Queue object (type is "TIF Queue").
These TIF Job business objects will after completion, at some point in the future, be deleted automatically by a scheduled task running at the TIF server. |
A job may be configured to be executed in one particular queue (if not defined, the default queue will be used). See chapter Create Trigger for some additional information. The reason for this might be to ensure that only certain TIF instances are processing certain jobs, and/or for scalability reasons.
A setup of TIF might look like the diagram below illustrates.
In this case we have four queues setup in ENOVIA™ and we are using two different TIF instances (TIF processes). TIF Instance 1 picks job from the default queue including the queue with name "Queue 1".
The second TIF instance processes jobs from "Queue 2" and "Queue 3".
To configure TIF for listening to a particular queue or configure it to NOT listen on the default queue, please look at the page Module Settings
In the module properties file you define which Queues you will listen to, e.g. what queues in ENOVIA you will process jobs for.
If you have setup several TIF instance, you may want to configure which instances that processes jobs from what queues.
By default, there is always a 'default queue' available in TIF. If you for example have multiple TIF instances running, each instance will by default process jobs from this default queue.
To disable listen on the default queue, you will use the following property
defaultQueueListener.enabled = false
Most common is to allocate jobs with the default queue. However, in some cases it might be useful to process certain jobs in its own queue. When you create the job object, you simply specify the name of the queue - this queue is automatically created if it doesn’t exist.
However, in order to process jobs from this queue, you need at least one TIF instance that listens on such queue.
In order to setup a listener for a particular queue, look at the example below:
queueListener.MyQueue.enabled = true
queueListener.MyQueue.name = My Queue
queueListener.MyQueue.threadCount = 5
queueListener.MyQueue.sleepInterval = 15000
queueListener.MyQueue.exclusive = false
The use of the prefix queueListener.MyQueue .
This prefix must be unique among your queues.
The name MyQueue may be whatever as long as the key itself is a valid Java property, however, recommended is to use something relevant for the queue in order to make debugging a bit easier.
|
The thread-count property defines how many worker threads will be used, e.g. how many concurrent jobs will be processed by this queue. Increasing this value will result in performance degradation.
The sleep-interval is a value in milliseconds defining how long time to sleep until next check (if no jobs were found in the queue in the previous check).
The exclusive flag should only be set if you are 100% sure that you don’t have any other TIF instance polling the same queue.
You may have the following optional properties:
queueListener.MyQueue.pickupDelay = 10
It is possible to configure pickup delay in seconds. In practice, the queue listener reacts on created jobs with delay by not picking up jobs created within queueListener.MyQueue.pickupDelay
.
The pickup delay works well in combination with exclusive jobs to prevent for example triggers from creating duplicate jobs.
It is also possible to configure pickup delay for jobs created in a certain queue OR for a certain job type via TVC init parameters . See ENOVIA Client part of the documentation.
|
To setup a new queue in ENOVIA, use the following MQL code as base for so.
add bus "TIF Queue" "MyQueue" "" vault "TIF" policy "TIF Queue";
Jobs are polled from the queue in the order they are created. E.g. first in first out.
This is by default accomplished by performing an expansion of the Queue with limit 1.
There has been some issues reported related to returning of jobs in wrong order. This is caused by a bug in ENOVIA and to workaround this issue - it is possible to change the polling strategy.
To change the polling strategy, use the property defaultQueuePollStrategy
in module.properties
.
Allowed values are
query-connection
expand-select
expand-iterator
expansion-iterator
mql-expand
mql-query
query
TIF will by default use either expand-iterator or expand-select depending on backend Database. But if you experience issues with job processing order, you should try changing this value to "query-connection".
An outbound integration job is a job that exports data from ENOVIA™ into another system (or systems) typically through some ESB (Enterprise Service Bus).
This kind of job is typically started based upon some event inside ENOVIA™, for example a lifecycle promote event or new object revision event triggers the job. This kind of job may also be started on demand or via a scheduled event.
You can trigger a job manually from the ENOVIA-MQL™ client like this example shows
execute program TIFTrigger -method newJob 1.2.3.4 tvc:jobcfg/NAME_OF_CONFIG.xml;
1.2.3.4
is an ENOVIA object identifier
You may for configurations in the default namespace omit the prefix tvc:jobcfg/
The jobs invoked in this manner are executed asynchronously, which is the normal usage pattern. If you need to invoke jobs in a synchronous way, please read this chapter. |
Read also this document for more information.
An integration job that will extract data from ENOVIA and send it to some destination is called "Transfer Data Job".
To define this kind of job, you need to create a job definition/configuration that defines first how to extract the data (e.g. the payload) but also define the destinations, which the data is transferred to.
Transfer data jobs support job events for handling errors etc. Read more in the "Job Event" chapter.
Before digging into the details of the configuration format for such a job, we will start by showing an example of how such a configuration can look alike.
<Job>
<TransferData>
<Payload>tvc:payload/PartReleased.xml</Payload>
<Destinations>
<SysOut/>
<File id="fileDest1"/>
<Http id="httpDest1"/>
<RabbitMQ id="rabbitMQ1">
<RetryAttempts>10</RetryAttempts>
<RetryDelay>5000,10000,20000,30000,60000</RetryDelay>
<Header name="type" value="${rpe:TYPE}" type="string"/>
<HeaderProvider>name of class implementing com.technia.tif.enovia.job.destination.HeaderProvider</HeaderProvider>
</RabbitMQ>
</Destinations>
</TransferData>
<Events>
<Error>
<SendMail>
<TO>...</TO>
<CC>...</CC>
<Subject>...</Subject>
<Message>
message...
${STACK_TRACE}
</Message>
</SendMail>
</Error>
</Events>
</Job>
The root tag in the definition is always <Job>
. The first child element of the Job element defines the kind of job, in this case we will use the <TransferData>
element to define the integration job.
Below the TransferData element, the following child elements are available.
<Payload>
Defines the name of the payload definition that defines how the payload is being created.
<Destinations>
Defines the destinations, to which the payload will be transferred.
<TransactionType>
Defines the ENOVIA transaction type to be used during the job.
Each of these elements are defined in more detail in the sub pages.
The Payload element points out the configuration that defines how to generate the payload (e.g. the data) from ENOVIA.
The value of the Payload element is either the XML configuration of type "payload" OR a Java class. See below for the two alternatives to define this.
Referencing a Payload Definition
Refer to payload configuration that contains the rules how to generate the payload.
<Job>
<TransferData>
<Payload>tvc:payload:namespace/ReleasedPart.xml</Payload>
The referenced Payload configuration is the file cfg/namespace/payload/ReleasedPart.xml
.
See page Payload Definition for details on how to define the payload definition.
Referencing a Custom Payload Generator
Refer to payload generator implemented in Java.
<Job>
<TransferData>
<Payload>java:com.acme.integration.MyPayloadGenerator</Payload>(1)
1 | Note that we use the "java:" prefix. The class must implement the interface com.technia.tif.enovia.payload.Payload |
The Destinations element within the <TransferData>
parent element contains the target destination (or destinations),
which the generated Payload will be transferred to.
The connection specific details for a connection is specified in a centralized file. Please look at the page Configure Destinations for further details on this topic.
The table below shows the supported destination elements.
Element | Descriptions | Supports Additional Headers | Supports Retry Attempt |
---|---|---|---|
|
Useful during development to see the payload printed out to the system output. |
No |
No |
|
Sends the payload into a file. |
No |
No |
|
Sends the payload to a HTTP endpoint. |
Yes |
Yes |
|
Sends the payload to a SOAP service |
No |
Yes |
|
Sends the payload to a JMS queue or topic |
Yes |
Yes |
|
Sends the payload to an Rabbit MQ queue/topic (via AMQP) |
Yes |
Yes |
|
Sends the payload to a Native MQ destination |
Yes |
Yes |
|
Sends the payload to a email recipient |
No |
No |
|
Defines a custom destination class. The class must extend from the base class |
- |
Yes (if class implements Retryable) |
The destination element(s) contains an "id" attribute, which refers to a corresponding destination definition within the However, the
|
Example
The example below will send the payload to:
the system-out (standard output)
file destination as configured with the ID "fileDest1" in the destinations.xml file
custom destination implemented by class "com.acme.integration.MyCustomDestination"
<Job>
<TransferData>
<Destinations>
<SysOut/>
<File id="fileDest1"/>
<SOAP id="webservice-test"/>
<Custom className="com.acme.integration.MyCustomDestination"/>
</Destinations>
</TransferData>
</Job>
You may specify conditions that must be met in order to transfer the payload to a certain destination.
Within the job configuration, the destination supports two different attributes called if
and unless
.
Here you specify the name (or names) of a property/parameter that must be OR must not be present on the Job itself in order to transfer the data to the destination in question.
Below is an example of using a conditionally inclusion of a destination:
<Job>
...
<TransferData>
...
<Destinations>
<Http id="http-1" if="send.to.1" />
<Http id="http-2" unless="send.to.1" />
</Destinations>
</TransferData>
</Job>
The subchapters below describes the configuration aspects for a JMS destination.
You can specify a destination to which replies are generated. This is done via the replyTo
attribute.
The value of this attribute must be the ID of an existing destination inside the destinations configuration file.
See chapter Configure Destinations for more information.
Below is an example how to configure the replyTo.
<JMS id="dest-id" replyTo="reply-dest-id" />
And within the destinations.xml
file:
<JMS id="dest-id"
initialContextFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
providerURL="tcp://172.16.16.141:61616">
<Queue name="part.info" jndiKey="queue.%s"/>
</JMS>
<JMS id="reply-dest-id"
initialContextFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
providerURL="tcp://172.16.16.141:61616">
<Queue name="part.info.reply" jndiKey="queue.%s"/>
</JMS>
When you have set the attribute replyTo, then you should setup a so called reply-handler that is able to update TIF when the reply arrives in order to track whether or not the integration job failed or not. If you do not set up such reply handler, your jobs will stay in the state "Awaiting Reply". See chapter Reply Handler for further details. |
The correlation id of a message is by default set to:
${tif.instance.id}|${job.id}|${destination.id}
This value contains macros, which during runtime are resolved to real values. The information in the correlation id is used for example by the reply handler to correlate a message back to its origin.
You may change this, but, please note that if you do then you must consider so in the reply-handler that you might use.
Below is an example how to configure the correlation id.
<JMS id="dest-id" correlationId="${job.id}/${destination.id}" />
The macros are described here |
You may specify a value for the JMS type property as shown below.
<JMS type="something" />
<JMS type="${macro}" />
The macros are described here |
You may specify a value for the JMS message priority as shown below. The priority is a value between 0 and 9.
<JMS priority="4" />
You may specify persistent or non-persistent delivery modes by specifying this
in the deliveryMode
attribute as shown below.
<JMS deliveryMode="non-persistent"/>
<JMS deliveryMode="persistent"/>
When seding data to a JMS destination, TIF will by default use a StreamMessage when sending the content.
If you for some reason want to change the type, you can do so as shown below.
<JMS id="the-id" messageType="text"/>
<JMS id="the-id" messageType="byte"/>
<JMS id="the-id" messageType="stream"/>
Some destinations allow additional meta-data to be passed along with the payload itself. Such meta-data is called headers and consists of key/value pairs.
A header value can be static or dynamic. It is also possible to provide a custom class that provides the headers. These are exemplified below:
<Job>
<TransferData>
...
<Destinations>
<JMS ...>
<!-- Static parameter -->
<Header name="test1" value="bar"/>
<!-- Dynamic parameter, value taken from RPE (ENOVIA Runtime Program Env) -->
<Header name="test2" value="${rpe:TYPE}"/> (1)
<!-- Dynamic parameter, value taken from the additional arguments -->
<!-- passed via the trigger program object in ENOVIA for this job -->
<Header name="test3" value="${paramName}"/>
<!-- Define a custom header provider -->
<!-- Such class must implement the interface: -->
<!-- com.technia.tif.enovia.job.destination.HeaderProvider -->
<HeaderProvider>com.acme.foo.MyHeaderProvider</HeaderProvider>
</JMS>
...
1 | The macros are described here |
The subchapters below describes the configuration aspects for a Rabbit MQ destination.
You can control the following aspects of a Rabbit MQ message:
Reply To
Correlation ID
Routing Key
Type
Priority
Delivery Mode
User ID
Application ID
You can specify an exchange to which replies are generated.
This is done via the replyTo
attribute.
The value of this attribute must be the name of an exchange in your Rabbit MQ broker.
Below is an example how to configure the replyTo.
<RabbitMQ id="rabbit-mq-dest-id" replyTo="NAME-OF-EXCHANGE" />
If a job is sent to a Rabbit MQ destination whose replyTo has been set, the job will after being processed get the status "Awaiting Reply."
When you have set the attribute replyTo, then you should setup a so called reply-handler that is able to update TIF when the reply arrives in order to track whether or not the integration job failed or not. If you do not set up such reply handler, your jobs will stay in the state "Awaiting Reply". See this chapter for further details. |
The routing key can be defined in the destinations.xml file, but a more flexible approach is to define the routing key per use-case.
The routing key can be defined as macro, allowing to resolve dynamic value based upon some parameter etc.
Example:
<RabbitMQ id="rabbit-mq-dest-id"
routingKey="${job.param.NAME-OF-PARAM}" />
The macros are described here |
The correlation id of a message is by default set to:
${tif.instance.id}|${job.id}|${destination.id}
This value contains macros, which during runtime are resolved to real values. The information in the correlation id is used for example by the reply handler to correlate a message back to its origin.
You may change this, but, please note that if you do then you must consider so in the reply-handler that you might use.
Below is an example how to configure the correlation id.
<RabbitMQ id="rabbit-mq-dest-id"
replyTo="NAME-OF-EXCHANGE"
correlationId="${job.id}/${destination.id}" />
The macros are described here |
You may specify a value for the type property as shown below.
<RabbitMQ type="something" />
<RabbitMQ type="${macro}" />
The macros are described here |
You may specify a value for the message priority as shown below. The priority is a value between 0 and 255.
<RabbitMQ priority="4" />
You may specify persistent or non-persistent delivery modes by specifying this
in the deliveryMode
attribute as shown below.
<RabbitMQ deliveryMode="non-persistent"/>
<RabbitMQ deliveryMode="persistent"/>
The subchapters below describes the configuration aspects for a IBM MQ / Native MQ destination.
You can specify a destination to which replies are generated. This is done via the replyTo
attribute.
The value of this attribute must be the ID of an existing native-mq destination inside the destinations configuration file.
See chapter Configure Destinations for more information.
Below is an example how to configure the replyTo.
<NativeMQ id="mq-dest-id" replyTo="mq-reply-dest-id" />
And within the destinations.xml
file:
<NativeMQ id="mq-dest-id"
queueManagerName="QM_technia_mq"
hostName="172.16.16.141"
port="1414"
characterSet="1208"
encoding="546"
channel="S_technia_mq"
connectOptions="">
<Queue name="partdata_req" options="INPUT_AS_Q_DEF,OUTPUT"/>
</NativeMQ>
<NativeMQ id="mq-reply-dest-id"
queueManagerName="QM_technia_mq"
hostName="172.16.16.141"
port="1414"
characterSet="1208"
encoding="546"
channel="S_technia_mq"
connectOptions="">
<Queue name="partdata_resp" options="INPUT_AS_Q_DEF,OUTPUT"/>
</NativeMQ>
When you have set the attribute replyTo, then you should setup a so called reply-handler that is able to update TIF when the reply arrives in order to track whether or not the integration job failed or not. If you do not set up such reply handler, your jobs will stay in the state "Awaiting Reply". See this chapter for further details. |
The correlation id of a MQ message is by default set to and ID, which resolves to the ID of the transfer.
A correlation id of a MQ message can only contain maximum 24 bytes. |
This value accepts macros, which during runtime are resolved to real values. The information in the correlation id is used for example by the reply handler to correlate a message back to its origin.
You may change this, but, please note that if you do then you must consider so in the reply-handler that you might use.
Below is an example how to configure the correlation id.
<NativeMQ id="dest-id" correlationId="${some.macro}" />
See this section for more details regarding macros.
A MQ Message sent from a TIF server contains per default the tif instance id as group id value. That information is used by reply handlers to only filter messages originating from a particular TIF instance.
If you only use one TIF instance, you may disable the use of group id’s.
To disable the use of group id’s, either specify this on the destination
element as shown below or globally in tif.custom.properties
using the
property nativeMQ.defaultUseGroupId = false
.
<NativeMQ id="..." setGroupId="false" />
There are different strategies available how to send the message. You may choose between one of the following
The message read into a string and is sent using the writeString
on the MQMessage
The message read into a string and is sent using the writeUTF
on the MQMessage
The message bytes are written using the write
method on the MQMessage.
You configure the strategy as shown below
<NativeMQ id="..." type="string" />
The default strategy is byte
.
On the destination definition you may specify character-set, encoding, priority and expiracy. See this section for more details.
However, you may override these on the <NativeMQ>
element per use case also.
Example:
<NativeMQ id="..."
encoding="546"
characterSet="1208"
priority="7"
expiracy="604800" />
The File destination contains one configurable options, e.g. define whether or not the result is updated asynchronously.
Example:
<File id="file-1" asyncReply="true" />
If you utilize this feature you should configure a so called reply handler. You can read more about reply handlers here |
The Email destination will by default include the content of the payload in the email as is (e.g. attachPayload is by default false). You can configure to attach the payload as a file to the mail instead, this is shown below.
<Email id="email-dest-1" attachPayload="true" attachAs="payload"/>
The attachAs
value is by default the static text payload
, and you may change this to something more appropriate.
The value may be a macro that resolves to some dynamic string.
The subchapter below describes the configuration aspects for a HTTP destination.
When data is transferred to a HTTP destination, the HTTP response status code is evaluated. By default, only the code "200 OK" is considered as success status code.
To override the default behavior, you can configure a custom list of success status codes via <SuccessStatusCodes>
configuration element. The element text must contain a comma separated list of codes.
Below is an example where "200 OK", "201 Created" and "202 Accepted" are considered as success status codes.
<Http id="my-http-dest">
<SuccessStatusCodes>200, 201, 202</SuccessStatusCodes>
</Http>
You may implement a custom Java class that can evaluate the HTTP response. The class must implement the interface com.technia.tif.enovia.job.destination.HttpStatusEvaluator
.
The interface is defined as below:
package com.technia.tif.enovia.job.destination;
import com.technia.tif.core.annotation.API;
import com.technia.tif.core.io.http.HttpResponse;
import com.technia.tif.enovia.job.EnoviaJob;
@API
public interface HttpStatusEvaluator {
/**
* Evaluates the HTTP response.
*
* @param job Job object
* @param response HTTP response.
* @return Whether the status evaluates to true or false.
*/
boolean evaluate(EnoviaJob job, HttpResponse response);
}
An example configuration:
<Http id="my-http-dest">
<StatusEvaluator className="com.acme.tif.MyStatusEvaluator" />
</Http>
Sometimes it is not possible to configure URL for HTTP destination in a static way, but it requires some input from the job being executed. To enable this, you may implement a custom Java class that can provide the URL.
The class must implement the interface com.technia.tif.enovia.job.destination.URLProvider
.
The interface is defined as below:
package com.technia.tif.enovia.job.destination;
import com.technia.tif.core.annotation.API;
import com.technia.tif.enovia.job.EnoviaJob;
@API
public interface URLProvider {
/**
* Provides URL. The implementation is responsible for possible URL
* encoding.
*
* @param job Job object
* @param destUrl URL configured in destination config
* @return URL
*/
String provide(EnoviaJob job, String destUrl);
}
An example configuration:
<Http id="my-http-dest">
<UrlProvider className="com.acme.tif.urlprovider.MyUrlProvider" />
</Http>
The subchapter below describes the configuration aspects for a custom destination.
When tranferring data to a custom destination, it might be useful to store information related to the transfer and view it in Admin UI afterwards.
This is possible by annotating field(s) containing the information with the annotation com.technia.tif.core.transfer.TransferProperty
.
The overall size of the information to be stored in TIF database is limited to 128k. |
For example:
import com.technia.tif.core.transfer.TransferProperty;
import com.technia.tif.enovia.job.TransferHandler;
public class MyDestination extends TransferHandler {
@TransferProperty
private int SomeField = 12345;
@TransferProperty
private String OtherField = "Hello World";
...
}
In addition, you may also return an object containing transfer properties by overriding the method getTransferProperties()
in the class that implements the custom destination.
The returned object is also available in the method transfer()
via argument TransferHandlerContext
.
For example:
import com.technia.tif.enovia.job.EnoviaJob;
import com.technia.tif.enovia.job.TransferHandler;
import com.technia.tif.enovia.job.TransferHandlerContext;
public class MyDestination extends TransferHandler {
@Override
public Object getTransferProperties(EnoviaJob job) {
return new MyProperties();
}
}
and
import com.technia.tif.enovia.job.EnoviaJob;
import com.technia.tif.enovia.job.TransferHandler;
public class MyProperties {
@TransferProperty
final boolean AnotherField = true;
}
The destinations that supports being retryable if the transfer fails are listed in the table above. Such destination can be configured like shown below:
<Job>
<TransferData>
...
<Destinations>
<JMS ...>
<RetryAttempts>20</RetryAttempts>
<RetryDelays>1000,5000,10000</RetryDelays>
The <RetryAttempts>
element defines how many times TIF will try to resend the payload to the destination.
The time to wait between two attempts is defined within the <RetryDelays>
element. This value contains comma separated integer values where each value defines a period in milliseconds.
In the example above, TIF will wait 1 second between the 1:st and 2:nd attempt; 5 seconds between the 2:nd and 3:rd attempt and 10 seconds between the 3:rd and all attempts up to the 20:th. If the destination fails after the max count has been exceeded, the job will be marked as failed.
The default values are:
Retry Attempts: 10
Retry Delays: 1000,5000,10000,20000,40000,60000
During the execution of the integration job of type "transfer data", TIF will by default start a READ transaction inside the ENOVIA database.
If you for some reason want to change this, you can do so like the example below illustrates.
<Job>
<TransferData>
<!-- used for read transaction (default) -->
<TransactionType>read</TransactionType>(1)
<!-- To start an update transaction -->
<TransactionType>update</TransactionType>(2)
<!-- To not start a transaction at all, use the value of none or inactive -->
<TransactionType>none</TransactionType>(3)
</TransferData>
</Job>
1 | Starts a read transaction |
2 | Starts an update transaction |
3 | Does not start a transaction |
This kind of integration job is used for launching external processes, with input that can be files that are checked-out from ENOVIA or data that is extracted from ENOVIA.
The output from the external processing can either be checked back into ENOVIA, for example if you perform conversion of files, or you can collect the output and send it to a destination, such as FTP or Webservice etc.
Before digging into the details of the configuration format for such a job, we will start by showing an example of how such a configuration can look alike.
The example below illustrates how to utilize the external process to convert files inside ENOVIA into different formats. For readability, only one conversion is included. It is however possible to run several executions to create multiple differet output variants.
<Job>
<ExternalProcess>
<Prepare>
<MkDir dir="input" id="in" />
<MkDir dir="output" id="out" />
<Checkout format="generic" file="*.png,*.jpg,*.gif" into="${path:in}/${filename}" id="src-file" />
</Prepare>
<Exec forEachFileRef="src-file">
<Executable>/usr/bin/magick</Executable>
<Arguments>
<Arg>${path:src-file}</Arg>
<Arg>-resize</Arg>
<Arg>120x120</Arg>
<Arg>${path:out}${separator}${filename:src-file}</Arg>
</Arguments>
<PostActions>
<Checkin
src="${path:out}${separator}${filename:src-file}"
format="Thumbnail"
fileName="${filename:src-file}"
overwrite="true" />
</PostActions>
</Exec>
</ExternalProcess>
<Events>
<Error>
<SendMail>
<TO>...</TO>
<CC>...</CC>
<Subject>...</Subject>
<Message>
message...
${STACK_TRACE}
</Message>
</SendMail>
</Error>
</Events>
</Job>
Another example illustrating how to generate some output that later is transferred to another system is shown below:
<Job>
<ExternalProcess>
<Prepare>
<ExtractPayload id="payload" config="MyPayloadConfig.xml" into="data.xml" />
<Checkout id="src-file" format="generic" fileName="*.abc" into="${filename}" />
</Prepare>
<Exec>
<Executable>/usr/bin/app</Executable>
<Arguments>
<Arg>${path:payload}</Arg>
</Arguments>
</Exec>
<Output stdout="true" stderr="true">
<Match dir="/" name="*.*" />
</Output>
<Destinations>
<File id="..." />
</Destinations>
</ExternalProcess>
</Job>
Many configuration aspects are the same as for transfer data.
The main difference is the <ExternalProcess>
element, which is described in the next chapter.
The <ExternalProcess>
element allows the following content
<Prepare>
Defines any preparations required. For example checkout files from ENOVIA or extract some payload data or create directories.
<Exec>
Describes what external process to execute, and what argument to pass.
You can define multiple <Exec>
elements if you need to invoke different processes
or invoke with different arguments.
<Output>
Optional element used to describe what output to collect from the external process. This is often used
together with <Destinations>
.
<Destinations>
Defines destinations. Please read more here.
Each of these elements are defined in more detail in the next chapters.
Preparing the external process execution is normally required. You may for example do any of the below:
Whenever you launch an external process, a dedicated working directory is created and the process is launched
with that directory as working dir. You can create additional subdirectories here-in. That is accomplished by the
<MkDir>
element.
You may checkout one or more files from the object, which you launch the job for. That is done via the <Checkout>
element.
You can also create meta data content using a payload definition. This is accomplished via the <ExtractPayload>
element.
For each of the prepare actions, you need to specify an id, which later is used when referencing the file or directory. The id is used in many macros, to resolve its path, absolute path, name or extension. Example:
|
Element | Attributes | Description | ||
---|---|---|---|---|
|
|
Creates a directory within the working dir. The dir attribute specifies the name of the directory. |
||
|
|
Checks out one or more files from ENOVIA.
The The |
||
|
|
Extracts the payload for the current object using the specified configuration and store the result in the specified file. |
The <Exec>
element defines what to execute and what arguments to supply to the external process.
This element supports the following attributes:
Attribute | Description |
---|---|
forEachFileRef |
Defines an optional ID that refers to a file or files, which is provided by a prepare action. If the file reference ID refers to a collection of files, the executable will be executed for each of them. |
processTimeout |
Defines a timeout in milliseconds, which if exceeded will cause the external process to be stopped. Note that by default, no limit is specified. |
And the supported child elements are
Element | Attributes | Description |
---|---|---|
|
- |
Defines the executable to be invoked. Example: |
|
- |
Defines the arguments to pass to the external process (see below). |
|
- |
Defines optional post actions to be performed. Currently, only Checkin is a supported post operation. |
The <Arguments>
element allows nested <Arg>
elements. Each occurence of such child element will result in an argument to be passed.
The <Arg> element may contain macros, which is resolved to file-ids from the preparation tasks.
Such macro may be define in a couple of different ways, see the table below:
|
Example | Description |
---|---|
|
Resolves the path relative from the working dir to the file with the specified ID. |
|
Resolves the absolute path to the file with the specified ID |
|
Returns the file name of the file with the specified ID |
|
Returns the file name excluding its suffix of the file with the specified ID |
|
Returns the suffix of the file with the specified ID |
Other supported macros:
Example | Description |
---|---|
|
The path separator for the current platform |
|
The separator for the current platform |
|
The ID of the current business object |
|
The workdir for the current execution (the absolute path) |
The currently supported post actions defined below <PostActions>
are shown below:
Element | Attributes | Description |
---|---|---|
|
|
Checks in the source file into ENOVIA. |
The <Output>
element is used when you want to collect the output from your external process.
The output will typically be a ZIP file unless you only want to collect the standard output OR standard error from the external process.
To get standard output or standard error as output without being zipped, set either attribute "stdout" OR "stderr" true, not both. Do not include any Match child elements. |
This element supports the following attributes:
Attribute | Description |
---|---|
stdout |
Defines if to include standard output. Default is false. |
stderr |
Defines if to include standard error. Default is false. |
And the supported child elements are
Element | Attributes | Description |
---|---|---|
|
|
Defines what content to include in the generated ZIP file. |
The <Match>
element will define what files to be included in the generated ZIP file.
Use wildcards on the name attribute to match more than one file.
Example:
<Output stdout="true">
<Match dir="${path:out-dir}" name="*.png" />
<Match dir="${path:out-dir}" name="*.gif" />
</Output>
You may in some cases need to create a job having customized logic. This is done by defining the class implementing the custom job logic inside the Executor tag as shown below.
<Job>
<Executor>com.acme.integration.executor.MyJobExecutor</Executor>
</Job>
The class must implement the interface com.technia.tif.enovia.job.JobExecutor
.
This interface is defined like below.
package com.technia.tif.enovia.job;
import com.technia.tif.core.ConfigurationException;
import com.technia.tif.core.ExtractionException;
import com.technia.tif.core.ValidationException;
import com.technia.tif.core.annotation.API;
/**
*
* @author Technia
* @since 31 okt 2012
*/
@API
public interface JobExecutor {
/**
* Executes the job using the provided data as input for the execution
*
* @param job The job to be executed
* @throws ConfigurationException May be thrown to indicate error in the
* configuration
* @throws ExtractionException May be thrown to indicate error while
* extracting data
* @throws ValidationException May be thrown to indicate error when
* validating the data being used/sent.
*/
void perform(EnoviaJob job) throws ExtractionException,
ConfigurationException,
ValidationException;
}
Custom jobs support job events for handling errors etc. Read more in the Job Events chapter.
By default, TIF does NOT start a transaction inside the ENOVIA database for the custom executor.
To change it, you can do so like the example below illustrates.
<Job>
<Executor className="com.acme.MyExecutor">
<TransferData>
<!-- used for read transaction -->
<TransactionType>read</TransactionType>(1)
<!-- To start an update transaction -->
<TransactionType>update</TransactionType>(2)
<!-- To not start a transaction at all, use the value of none or inactive (default) -->
<TransactionType>none</TransactionType>(3)
</TransferData>
</Executor>
...
</Job>
1 | Starts a read transaction |
2 | Starts an update transaction |
3 | Does not start a transaction |
It is possible to store outbound payload that is visible in Admin UI. Use com.technia.tif.enovia.job.log.Logger
.
For example:
import com.technia.tif.enovia.job.EnoviaJob;
import com.technia.tif.enovia.job.JobExecutor;
import com.technia.tif.enovia.job.log.Logger;
import com.technia.tif.enovia.payload.impl.PayloadDataBuffer;
public class MyJobExecutor implements JobExecutor {
@Override
public void perform(EnoviaJob job) {
Logger.storeOutboundPayload(job, new PayloadDataBuffer().append("Hello World!"));
}
}
If you have a license to the "TVC File Manager" component, you are maybe familiar with the feature called File Package Download.
This feature lets you configure the creation of a ZIP package containing files checked-in to objects in ENOVIA, files containing meta-data from ENOVIA and/or other files.
The File Package configuration format is described in the "TVC File Manager" documentation.
The File Package job works in the same way as the Transfer Data job, the only
difference is that you for the <FilePackage>
element need to define the file package
creation rules.
One way to create a file package is to point out a File Package configuration. The format of such configuration is defined in the TVC File Manager documentation.
Below is an example how to accomplish this:
<Job>
<Name>PDX Creation</Name>
<FilePackage>
<Config>tvc:fpd:tvx:enc/PDX.xml</Config> (1)
<Destinations>
<File id="file-dest-3"/>
</Destinations>
</FilePackage>
</Job>
1 | Point out the FPD configuration |
A special TIF handler is provided as a part of the product. This handler can be used to specify what data to be included such as files and payload content into the generated package.
An example is shown below:
<Job>
<Name>PDX Creation</Name>
<FilePackage>
<Content>
<Files dataSet="tvc:dataset/PartSpecifications.xml"
saveIn="specifications/${id}/${format}">
<FileFilter>
<Exclude>
<Name>*.exe</Name>
<Name>*.sh</Name>
<Name>*.abc</Name>
<Format>format_JT</Format>
<Format>format_Secret</Format>
</Exclude>
</FileFilter>
</Files>
<Files dataSet="tvc:dataset/RefDocs.xml"
saveIn="refdocs/${id}/${format}">
<FileFilter>
<Include>
<Name>*.docx</Name>
<Name>*.xlsx</Name>
<Name>*.doc</Name>
<Name>*.xls</Name>
<Name>*.pdf</Name>
</Include>
</FileFilter>
</Files>
<Payload config="tvc:payload/BOM.xml" saveIn="data" saveAs="bom.xml" />
<Payload config="tvc:payload/Specs.xml" saveIn="data" saveAs="specs.xml" />
<Payload config="tvc:payload/RefDocs.xml" saveIn="data" saveAs="ref-docs.xml" />
</Content>
<Destinations>
<File id="file-dest-3"/>
</Destinations>
</FilePackage>
</Job>
Within the <Content>
element you may declare elements of type <Files>
and <Payload>
,
which will define the files to be added to the package including what payload/meta-data
to be included.
For the Files element you need to point out a data-set, which should return business objects that contains files. Each of the files found from these objects will be added, unless any exclusion/inclusion rules denies so, to the package.
Inclusion/Exclusion can be specified with either a file-name pattern or based upon format.
The <FileFilter>
can be shortened, and be written like these examples:
<FileFilter includeFormats="a,b,c" /> <FileFilter excludeFileNames="*.exe,*.dll" /> <FileFilter excludeFormats="a,b,c" /> <FileFilter includeFileNames="*.exe,*.dll" />
Note that the files found should be saved in a way, which prevents them from overwriting each other.
Typically you need to use object-id and format as a part of the folder name. The default saveIn
value
unless specified is files/${id}/${format}
.
For Payload data inclusion, you need to specify the payload configuration as minimum.
Optionally, you can specify the folder to save the data in with the saveIn
attribute.
The saveAs
attribute specifies the file name of the payload data. By default, the
file name is constructed using this file name format payload_%03d.xml
. The format
will get the payload sequence number as input. E.g the %03d
will then be converted
to "000" for the first payload.
A simpler configuration allows pointing out a so called File Package Download handler directly, without having to specify a FPD config that in turn points out the handler.
See below for an example:
<Job>
<Name>PDX Creation</Name>
<FilePackage>
<Handler className="com.acme.fpd.MyFPDHandler" /> (1)
<Destinations>
<File id="file-dest-3"/>
</Destinations>
</FilePackage>
</Job>
1 | Define the class name inline |
From a performance perspective one should avoid using synchronous integrations, since that may block the user from working with the ENOVIA™ system in a smooth way. However, in some situations it is necessary to run a job synchronously.
Remember that TIF is running in a different process than your ENOVIA app. If you have started a transaction and within that transaction performs a synchronous call to TIF, you need to extract the data you need (the payload) on the TIF server before you do the TIF call. Otherwise you may due to transaction isolation not be able to read the correct data OR you may in worst case cause a dead-lock. |
On the caller side, you typically use the method |
In order for the client to know where the TIF server is located, you need to set some environment variables.
The URL to the TIF server is resolved in the following order:
Java system parameter: System.getProperty("tif.server.url")
TVC Init parameter: tif.server.url
(set in web.xml or /WEB-INF/classes/tvc.properties).
ENOVIA RPE Parameter: TIF_SERVER_URL
ENOVIA Ini Parameter: TIF_SERVER_URL
Environment Variable: TIF_SERVER_URL
The default is /enovia/tif-internal. Unless you have changed this via the module settings file, you do not need to set this. Otherwise, this value is resolved in the same order as above:
Java system parameter: System.getProperty("tif.server.contextPath")
TVC Init parameter: tif.server.contextPath
(set in web.xml or /WEB-INF/classes/tvc.properties).
ENOVIA RPE Parameter: TIF_SERVER_CONTEXTPATH
ENOVIA Ini Parameter: TIF_SERVER_CONTEXTPATH
Environment Variable: TIF_SERVER_CONTEXTPATH
You can embed the invocation of a synchronous job in your own code by using the TIF classes like shown below:
...
import com.technia.tif.enovia.api.synch.InvokeJobResponse;
import com.technia.tif.enovia.client.synch.SynchCreateNewJob;
...
Map<String, String[]> paramMap = ...
SynchCreateNewJob req = new SynchCreateNewJob();
req.setJobCfg(jobCfg);
req.setParamMap(paramMap);
//req.setPayload(aString);
InvokeJobResponse response;
try {
response = req.run();
} catch (XMLException | IOException e) {
throw new AppException("Unable to run integration", e);
}
if (response.getHasError()) {
throw new AppException(response.getErrorMessage());
}
String firstResult = response.getFirstResult().getResponse();
...
If you use the TVC Structure Browser component within your ENOVIA web application, you can use a built in processor for name-allocation from an external system.
Please look into this tutorial for additional information and usage.
Inbound integration jobs in TIF are based upon some external event resulting in some kind of job taking place at the TIF server.
Such job typically performs some update to the ENOVIA™ database, for example creates or updates business objects and/or connections between business objects. It may however also be a job that only fetches data from ENOVIA™, for example some external system requests some data from ENOVIA™ via a JMS message or a Webservice request.
The use cases varies. The child pages describes the current possibilities to handle this within the TIF server.
TIF includes an Apache Axis2 installation in order to support SOAP based web-services.
In addition to the standard distribution of Apache Axis2, TIF provides some extended Axis2 functionality that supports creation and deployment of some different kind of SOAP based web-services solely defined in XML file. E.g. no need to implement the webservice in Java, compile and package it as a AAR file.
The kind of configurable web-services you can use in the current TIF release are:
Export of data from business object(s).
The configuration format allows specifying criteria used to find the business object(s) to export
Also, you configure what data to be exported for these objects.
It is also possible to point out a Payload Definition that defines the returned meta-data
Update of business object(s) data
The configuration format allows specifying criteria used to find the business object(s) to update
Also, you configure what fields / attributes the web-service client may update and some rules for the values.
The first service is called "configurable export service" and the second is called "configurable update service".
These are described in more detail in the child pages.
A configurable web-service is defined in an XML file that should be put inside the following folder:
${TIF_ROOT}/modules/enovia/cfg/soapservice
By default, TIF has enabled hot-deployment and hot-update of the Axis2 application meaning that you can add new configurable web-services or update existing at runtime of TIF.
The web-service definition is defined by you and consists of an XML file. When this file is put into the directory "soapservice", the TIF deployer in Axis2 will pick up the file and scan it. The following actions will take place then:
Parse and validate definition
Generate a WSDL
Compile the WSDL into Axis Data Binding classes (ADB)
Generate Java code implementing the service classes.
Compiles all source code.
Packages all compiled artifacts along with necessary resource into a so called AAR file (Axis archive).
The AAR file is deployed into Apache Axis2.
Service is ready for use
The final AAR files are stored internally under the following folder inside TIF:
${TIF_ROOT}/data/${TIF_INSTANCE_ID}/axis2/services
There are some common settings possible to define on a configurable web service. These are defined as attributes on the root-element in the XML definition.
The attributes are:
Attribute Name | Description | Required |
---|---|---|
namespace |
Used to specify the namespace of the schema in the WSDL. |
No |
package |
Unless defined, a default package name for the generated Java classes will be used. Note that if you define your package name, ensure that it is unique and will not collide with existing web-service’s. |
No |
keepSource |
A boolean flag that may be used to keep the generated source files. This might be useful for debugging purposes. |
No |
debug |
If set to true the source code is generated with some debug information. |
No |
serviceDescription |
Gives the service a more human friendly description. Unless specified, the service description will be the same as the service name. |
No |
The URL to a configurable web service depends on what hostname your TIF server uses, the port TIF will be using (8181 is default), the context path to the jaxws application and finally the name of the XML definition that defines the webservice.
Assuming your configurable webservice is defined in a file called ProductQueryService.xml and the default configurations are used, the URL becomes
http(s)://tif-server:8181/enovia/jaxws/services/ProductQueryService
To obtain the WSDL file for this service, just append the ?wsdl
at the end of the URL.
Axis2 Installation Details
The Apache Axis2 installation is part of the TIF installation. The place where the Axis2 related files are installed is:
${TIF_ROOT}/modules/enovia/webapps/jaxws
TIF has made some changes into the Axis2 configuration files. If you do any changes in the Axis2 configuration files, ensure that you don’t remove or destroy the TIF specific additions. |
The configurable export web-service support is used to quickly setup a SOAP based web-service that can be used by a client to export business object meta data.
Each configuration results in one web-service to be exposed. This kind of web service may have one or two operations (or methods) that can be invoked remotely, namely:
Extracting data based upon a list of object id’s
Extracting data from object(s) based upon query parameters deciding what object’s to be exported
Below is a sample configuration illustrating some concepts.
<ExportServiceDefinition>
<Credentials required="true" />
<ObjectId max="100" />
<Query>
<Params>
<Limit min="1" max="50" />
<Name allowWildCard="true" />
</Params>
<Defaults>
<Limit>25</Limit>
<Type>type_Product</Type>
<Vault>vault_eServiceProduction</Vault>
<Revision>*</Revision>
<Where>current matchlist 'Release,Obsolete' ','</Where>
</Defaults>
</Query>
<Extract payload="tvc:payload/ProductDetails.xml"/>
</ExportServiceDefinition>
The root element of this file must be <ExportServiceDefinition>
.
The available child elements are listed in the table below.
Child Element | Description | Example |
---|---|---|
|
Defines if the client of this web-service must provide a user name / password for an ENOVIA user. If the definition does not contain this element or has the attribute required set to false, the query and data extract will be performed with super-user privileges. |
No but recommended. |
|
Defines if an operation in the web-service called "getDataForObjectId" should be available. This method allows passing in ENOVIA object-id’s to the service in order to extract data. Note that the service will not perform any check of the validity of these object-id’s. For example, a client might pass object-id’s pointing to for example business objects of type Part to a service that normally deals with Products. |
No but either this or the <Query> element must be present. |
|
Defines if an operation in the web-service called "query" should be available. Depending on the content of this element, the query method can accept a wide range of different input. See below for further details. |
No but either this or the <ObjectId> element must be present. |
|
Defines what to be extracted from this web-service. You may point out a payload configuration or define selectables directly in the configuration. |
Yes |
|
Defines a custom Java class OR a custom Script file that can be used to perform additional validations. |
No |
Credentials
If this element is omitted or if the attribute required is set to false then the operations or methods of this web service will be executed with admin privileges.
Example:
<ExportServiceDefinition>
<Credentials required="true"/>
If credentials is required, the user calling the web-service operation is required to enter a valid ENOVIA user id / password combination.
It is also possible to use container managed authentication (basic authentication). See [Container Managed Credentials] for more information.
ObjectId
If the <ObjectId>
element is present, this will result in that an operation called getDataForObjectId()
is available on the web service.
This element may have one attribute defined called "max". This attribute may be used to limit the number of object-id’s that are allowed to pass in to the operation.
The default value is "-1", meaning that there is no upper limit.
Example:
<ExportServiceDefinition>
...
<ObjectId max="-1"/
Query
If the <Query>
element is present, this will result in that an operation called "query" is available on the web service.
The query method will accept some input arguments, which are defined by the definition. Lets take a closer look what child elements you may have for the <Query>
element:
Child Element | Description | Required |
---|---|---|
|
Defines what parameters the client may pass in. See below for details. |
No, but probably always used. |
|
Defines some default settings for the query, such as default where expression or default type pattern etc. |
No, but for security reasons recommended as you may not want the client to be able to search upon any data inside the ENOVIA database. |
These child elements are described below.
Params
The <Params>
element defines what input arguments the client may pass in.
The possible child elements are shown in the table below:
Child Element | Description | Attributes | Required | Example |
---|---|---|---|---|
|
Used to allow the client to define a query limit. You may also say what the min and max value for the limit can be. |
min max value |
No |
|
|
If present, allows the client to define a type pattern for the query. The attribute "wildcardAllowed" may be used to specify if characters such as * and/or ? may be used in the pattern. The attribute "name" may be used to give this parameter a different name. |
wildcardAllowed name |
No |
|
|
Same as |
See above |
No |
|
|
Same as |
See above |
No |
|
|
Same as |
See above |
No |
|
|
Same as |
See above |
No |
|
|
Defines an argument that affects the where clause of the query. The Arg element has a child element called The name attribute is used to provide this argument a valid name. The required attribute specifies if the client must provide this value or not. The type attribute may be one of: string, integer, decimal, boolean The rangeLoader attribute may be used to point out a custom range value provider.
The class must implement the interface: |
name required type rangeLoader |
No |
|
Arg / Where
Within the where clause of the argument, you use the %s
(String.format is used for this) to be replaced with the real value. Note that you might use other format options if you are familiar with the Formatter / String.format in Java.
Defaults
The <Defaults>
element defines the default search criteria.
The possible child elements are shown in the table below:
Child Element | Description | Required | Example |
---|---|---|---|
|
Specifies the default find/query limit |
No |
|
|
Defines a type in the type pattern. Each type in the pattern is defined inside it’s own Type tag. |
No |
|
|
See |
No |
|
|
See |
No |
|
|
See |
No |
|
|
See |
No |
|
|
Defines the default part of the where clause. Note: This where expression will be added first to the where clause, before any custom arguments. |
No |
|
Extract
The <Extract>
element defines what data to be extracted for the objects found via the query (or the objects provided by the getDataForObjectId()
operation).
You have two different options to perform the extract, either point out a payload definition that specifies what data to be extracted, or define it in this configuration.
For the first alternative, e.g. using a payload definition, you configure that scenario like shown below:
<ExportServiceDefinition>
<Extract payload="tvc:payload/MyPayload.xml" />
or
<Extract payload="MyPayload.xml"/>
For the other alternative, the possible child elements are shown in the table below:
Child Element | Description | Attributes | Required | Example |
---|---|---|---|---|
|
Defines that the basic data from the business object(s) may be part of the extracted data, if the client wants it. You may define certain basic properties to be excluded by using the The name attribute is default set to "basics". The default attribute is default set to "include". |
name default |
No |
|
|
Defines that the attributes from the business object(s) may be part of the extracted data, if the client wants it. You may define certain attributes to be excluded by using the <Exclude> child element The name attribute is default set to "attributes". The default attribute is default set to "include". |
name default |
No |
|
|
Defines custom extraction arguments. See details below. |
name default dataType select |
No |
|
Arg
The <Arg>
element is used to specify custom extract arguments. E.g. one argument may map to one or multiple select expressions. You may also refer to a "table column definition", which defines complex data extraction rules.
The following table shows the available attributes on the <Arg>
element.
Attribute Name | Description | Example |
---|---|---|
select |
Defines a single select expression |
|
dataType |
Defines the data type of the returned data. One of:
|
|
multiple |
A boolean indicating if the returned data contains one or multiple values. If a select expression starts with "from[", "to[" or "relationship[", this value will by default be set to true. |
|
The possible child elements are shown in the table below:
Child Element | Description | Required | Example |
---|---|---|---|
|
Defines a select expression that should be used for extraction of the data |
No |
|
|
Defines a table column that is used for extraction of the data |
No |
|
Handler
The handler element allows pointing out a custom Java class or a custom script for validation/custom handling of the web service. The latter is a convenient way to quickly implement custom validation without having to compile any code.
To define a custom Java class, configure it like shown below:
<ExportServiceDefinition>
<Handler>com.acme.integrations.ws.ProductDataExportHandler</Handler>
This class must either implement the interface com.technia.tif.enovia.jaxws.api.export.QueryServiceHandler
or extend from the default implementation com.technia.tif.enovia.jaxws.api.export.DefaultQueryServiceHandler
.
The default implementation is implemented like shown below:
import java.util.Map;
import com.technia.tif.enovia.jaxws.api.Value;
import com.technia.tif.enovia.jaxws.api.Webservice;
import com.technia.tvc.core.db.Query;
public class DefaultQueryServiceHandler implements QueryServiceHandler {
public void validateInput(Webservice service, Object input) {
}
public void validateQuery(Webservice service, Query query) {
}
public void handleBasicsMap(Webservice service, Map<String, Value> valueMap) {
}
public void handleAttributesMap(Webservice service, Map<String, Value> valueMap) {
}
public boolean isAuthorized(Webservice service, String userId) {
return true;
}
}
If you want to implement the same handler in a script file, for example a Javascript file you can point out such script like shown below (different syntaxes shown).
<ExportServiceDefinition>
<Handler>script:MyHandler.js</Handler>
<Handler>tvc:script/MyHandler.js</Handler>
<Handler>script:tvc:script/MyHandler.js</Handler>
<Handler>tvc:script:acme/MyHandler.js</Handler>
The first three variants all refers to the same script file, e.g. ${TIF_ROOT}/modules/enovia/cfg/script/MyHandler.js
The last example refers to the file: ${TIF_ROOT}/modules/enovia/cfg/acme/script/MyHandler.js
You may chose what functions to implement in your script, below is an example:
function validateInput(service, input) {
var qp = input.getQueryParams();
var arg1 = qp.getArg1(), arg2 = qp.getArg2();
if (arg1 == "1" && arg2 == "1") {
throw "Arg1 and Arg2 may not both be set to 1";
}
}
function isAuthorized(service, uid) {
if (uid == "creator") {
return false;
}
return true;
}
The configurable update web-service support is used to quickly setup a SOAP based web-service that can be used by a client to update business object meta data in ENOVIA™.
Each configuration results in one web-service to be exposed. This kind of web service will have one operation that can be invoked remotely. This method is called "update".
Below is a sample configuration illustrating some concepts.
<UpdateServiceDefinition>
<Credentials required="true" />
<Query>
<Params>
<Arg name="unitOfMeasure" required="true" type="String">
<Where>${attribute[attribute_UnitofMeasure]} == "%s"</Where>
</Arg>
</Params>
<Defaults>
<Limit>100</Limit>
<Type>type_Part</Type>
<Vault>vault_eServiceProduction</Vault>
</Defaults>
</Query>
<Update>
<Field
name="unitOfMeasure"
type="string"
attribute="attribute_UnitofMeasure"/>
<Field
name="test"
type="string"
required="false"
java="com.technia.tif.enovia.jaxws.api.update.TestUpdater"/>
</Update>
<ReturnFormat>
<OnSucess>
<Status>OK:${COUNT}</Status>
</OnSucess>
<OnError>
<Status>FAILED</Status>
<Message>${ERROR}</Message>
</OnError>
</ReturnFormat>
</UpdateServiceDefinition>
The root element of this file must be <UpdateServiceDefinition>
.
The available child elements are listed in the table below.
Child Element | Description | Required |
---|---|---|
|
Defines if the client of this web-service must provide a user name / password for an ENOVIA™ user. If the definition does not contain this element or has the attribute required set to false, the query and data extract will be performed with super-user privileges. |
No but recommended |
|
Defines the query parameters, e.g. the query that returns the objects which is subject for being updated. |
Yes |
|
Defines what to be updated, e.g. what input the client must provide and what this input maps to. |
Yes |
|
Defines the response/return value from the service. You may configure the success message and error message / status. |
No |
|
Defines a custom Java class OR a custom Script file that can be used to perform additional validations. |
No |
Credentials
If this element is omitted or if the attribute required is set to false then the operations or methods of this web service will be executed with admin privileges.
Example:
<UpdateServiceDefinition>
<Credentials required="true"/>
...
If credentials is required, the user calling the web-service operation is required to enter a valid ENOVIA™ user id / password combination.
It is also possible to use container managed authentication (basic authentication). See [Container Managed Credentials] for more information.
Query
The details of the <Query>
element is described within the Configurable Export Service chapter.
Update
The <Update>
element defines what to be updated.
The following table shows the possible child elements of this element.
Child Element | Description | Required | Example |
---|---|---|---|
<Field> |
Defines the "fields" that contains the update settings |
At least one present |
|
Field
The <Field>
element has a number of attributes used to control the behavior of the field. The following table shows the available attributes on the <Field>
element.
Attribute Name | Description | Example | Required |
---|---|---|---|
name |
Defines the name of the field. Note that the name must only contain the characters a-z and or A-Z or digits. The first character must be a letter. |
|
Yes |
type |
Defines the data-type for the value sent by the client. The possible values are:
|
|
No, defaults to String |
attribute |
Specifies an attribute, which the field maps to. |
|
- |
basic |
Specifies a basic property, which the field maps to. |
|
- |
java |
Specifies a Java class, which the field maps to. See below for details |
|
- |
script |
Specifies a Script file, which the field maps to. See below for details |
|
- |
Exactly one of the attributes "attribute", "basic", "java" and "script" must be set. |
The Java attribute, if used, must contain the fully qualified classname of a class implementing the interface com.technia.tif.enovia.jaxws.api.update.Updater
.
This interface is defined as below:
package com.technia.tif.enovia.jaxws.api.update;
import com.technia.tif.enovia.jaxws.api.Webservice;
/**
* The updater interface used by the configurable update webservice.
* @author Technia
*/
public interface Updater {
/**
* Performs the update of the field.
*
* @param service The service, which is calling this updater.
* @param objectId The id of the object to update
* @param field The field name to be updated
* @param value The value sent by the client.
* @throws Exception If unable to perform the update operation, for some reason.
*/
void update(Webservice service, String objectId, String field, Object value) throws Exception;
}
Using the script attribute lets you define the update logic inside a script file instead. Below is an example of such:
importClass(com.technia.tvc.core.db.BusinessObjectUtils);
function update(service, objectId, field, value) {
var type = BusinessObjectUtils.select(objectId, "type.kindof");
if (type == "Part") {
if (value < "1") {
throw "Invalid value: " + value;
}
BusinessObjectUtils.setAttribute(objectId, "Target Cost", value);
}
}
ReturnFormat
The <ReturnFormat>
element allows defining how the response should look alike when the web-service has been invoked.
You can control the success status and the error status and message. See below for syntax:
<UpdateServiceDefinition>
<ReturnFormat>
<OnSucess>
<Status>OK:${COUNT}</Status>
</OnSucess>
<OnError>
<Status>FAILED</Status>
<Message>${ERROR}</Message>
</OnError>
</ReturnFormat>
</UpdateServiceDefinition>
The ${COUNT}
macro refers to the number of objects being updated.
The ${ERROR}
macro may be used in the <OnError>
section to include the error message.
Handler
The <Handler>
element is described in the Configurable Export Service chapter.
The <Credentials>
element contains the following attributes:
A boolean value. Specifies if authentication is carried out via the servlet container. See chapter below how to configure this.
A string value. Defines the name of the ENOVIA™ user that we will run the service as.
A boolean value. Useful together when containerManaged=true
and
you want to run the service as a super user, while authentication is required.
Valid child elements are defined in the table below
Element | Description | Mandatory |
---|---|---|
|
Used for defining the ENOVIA/3DExperience security context. See below how to configure this. |
No |
|
In case container managed authentication is enabled, you may define additional roles, which the authenticated user must have in order to gain access. These roles are typically not ENOVIA/3DExperience roles, in case of Kerberos authentication these will be roles from your Active Directory. Note that if you specify multiple roles, the user is only required to have one of the listed roles in order to get access. Example below:
|
No. |
|
Specify additional ENOVIA/3DExperience assignments the user must have in order to proceed. Example below:
|
No |
Via the <SecurityContext>
element you define what security context to use.
You may do the following.
Point out a mapping file
Or use a default mapping file
Specify a named security context
Or use the "default" security context as configured for the ENOVIA user
To point out a mapFile use the syntax below.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext mapFile="sec-mapping.xml" />
Use the default mapping file.
The default file is specified via the property securityMapping.defaultFile
, and the default value is security-context-mapping.xml
.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext useDefaultMapFile="true" />
The format of the mapping file is shown below:
<Contexts>
<Context name="Design Engineer.Company Name.GLOBAL">
<User is="user1" />(1)
<User is="user2" />
<User is="user3" />
<Role is="engineer" /> (2)
<Role is="designer" />
<Parameter name="test" is="something" /> (3)
<Parameter name="x" is="y" />
</Context>
<Context name="...">...</Context>
<Context name="...">...</Context>
</Contexts>
NOTE that specifying user and role requires having enabled container managed authentication (Kerberos or Basic Authenticaton etc.)
1 | Specifies certain users to match against |
2 | Specifies additional roles the user should have |
3 | Specifies additional parameters and value to be evaluated In case of a REST service, the parameters are the request parameters passed to the service. |
The evaluation logic is:
User list is EMPTY or user is in list
Role list is EMPTY or user have one of the roles in the list
Parameter list is EMPTY or one of the parameters have the expected value
If A AND B AND C is satisfied, then use the security context defined for this "rule".
To use a specific Security Context:
<SecurityContext use="Design Engineer.Company Name.GLOBAL" />
Specify using the default security context.
<SecurityContext useDefault="true" />
You can enable security on the servlet container level and either use Kerberos/SPNego authentication OR use Basic authentication and authenticate against the ENOVIA™ database.
Within the ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
, you need
to specify what login service to be used including its realm and optionally some
extra parameters.
The login services currently supported are
A login service that will authenticate the remote user against the ENOVIA™ database.
A login service that will authenticate the remote user against a LDAP directory (for example Active Directory)
A login service supporting Single Sign On against Active Directory.
In order to use Spnego authentication, also read this document in order to setup the core parts of Spnego/Kerberos. |
If the "loginService" is set to "ldap", TIF will authenticate users against a LDAP directory.
http.webapp.jaxws.loginService=ldap
http.webapp.jaxws.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
There are some additional LDAP settings required to be defined. You can specify global LDAP parameters and/or web application specific LDAP parameters. In most cases you will be fine with only global LDAP settings.
For convenience, the application specific parameters will be merged with the global LDAP parameters. Hence you only need to override/define the parameters that is different on the application level.
Please see the table below.
The global parameter name is ldap. , while the application specific parameter
are named like http.webapp.<APP_NAME>.ldap.
|
Parameter | Description | Required |
---|---|---|
ldap.server |
Defines the server or list of LDAP servers. Separate with space if using multiple. |
Yes |
ldap.rootDN |
Defines the root dn, where all LDAP searches starts from. If we can start a search starting at a sub-node (as opposed to root), you get a better performance because it narrows down the scope of a search. This field specifies the DN of such a subtree. |
No |
ldap.userSearchBase |
The relative DN (From the root DN) that further narrow down searches to the sub-tree. If you do specify this value, the field normally looks something like "ou=people". |
No |
ldap.userSearchFilter |
This field determines the query to be run to identify the user record. The query is almost always "uid={0}" as per defined in RFC 2798, so in most cases you should leave this field empty and let this default kick in. If your LDAP server doesn’t have uid or doesn’t use a meaningful uid value, try "mail={0}", which lets people login by their e-mail address. If you do specify a different query, specify an LDAP query string with marker token "{0}", which is to be replaced by the user name string entered by the user. |
Yes |
ldap.groupMembershipAttribute |
If the user entry in the LDAP tree contains an attribute with the group membership, then specify that attribute here. Otherwise we need to query for the groups a user belongs to. |
Either this or the groupSearchBase / groupSearchFilter needs to be defined. |
ldap.groupSearchBase |
This field determines the query to be run to identify the organizational unit that contains groups. The query is almost always "ou=groups" so try that first, though this field may be left blank to search from the root DN. |
Not needed, but if the groupMembershipAttribute is undefine you can use this to make the group query faster. |
ldap.groupSearchFilter |
Defines the search filter for groups. In case we need to search the LDAP tree for group membership this needs to be defined. The marker token "{0}" is replaced with the current user’s DN. Example:
|
Yes unless groupMembershipAttribute is defined. |
ldap.managerDN |
If your LDAP server doesn’t support anonymous binding, then we would have to first authenticate itself against the LDAP server. A DN typically looks like CN=MyUser,CN=Users,DC=mydomain,DC=com although the exact sequence of tokens depends on the LDAP server configuration. It can be any valid DN as long as LDAP allows this user to query data. |
Probably Yes |
ldap.managerSecret |
The password for the manager DN |
Probably Yes |
ldap.displayNameLDAPAttribute |
The attribute holding the display name. Per default we use the CN of the user entry. |
No |
ldap.emailAddressLDAPAttribute |
The attribute holding the email value. Per default we use the field This field is currently not used so you can leave it blank. |
No |
ldap.pooled |
Whether or not to pool the LDAP connections |
No |
Example setup below for Active Directory.
ldap.server=ldapserver.yourdomain.com:3268
ldap.rootDN=DC=yourdomain,DC=com
ldap.managerDN=CN=nameofuser,CN=groupforuser,DC=yourdomain,DC=com
ldap.managerSecret=the_very_secret_string
ldap.userSearchBase=
ldap.userSearchFilter=(&(objectClass=person)(|(sAMAccountName={0})(userPrincipalName={0}@*)))
ldap.emailAddressLDAPAttribute=mail
ldap.displayNameLDAPAttribute=displayName
ldap.groupMembershipAttribute=memberOf
#ldap.groupSearchBase=OU=groups
#ldap.groupSearchFilter=(&(member={0})(objectClass=group))
The managerSecret value can either be defined in plain text, or you can encrypt the password from an MQL client using the "mql encrypt" feature.
The encrypted value can be used in the configuration file if you add the prefix Eg.
|
If the "loginService" is set to "enovia", TIF will authenticate users against the ENOVIA database.
http.webapp.jaxws.loginService=enovia
http.webapp.jaxws.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
Secondly, an example for spnego:
http.webapp.jaxws.loginService=spnego
http.webapp.jaxws.spnego.targetName=HTTP/tifserver.exampledomain.com
http.webapp.jaxws.realm=Webservices
Instead of specifying the targetName you may instead point out a property file that holds that value under the key targetName. See below: |
http.webapp.jaxws.loginService=spnego
http.webapp.jaxws.spnego.config=${tif.home}/etc/kerberos/spnego.properties
http.webapp.jaxws.realm=Webservices
The spnego.properties
defines the targetName like this:
targetName = HTTP/tifserver.exampledomain.com
Within the "web.xml" file (webapps/jaxws/WEB-INF/web.xml) you need to setup the rules for the application.
If you have not started TIF, you will not find the web.xml file, instead
it will be found under webapps/jaxws/WEB-INF/web.xml.template . Upon start, TIF
will copy over the template file unless the web.xml file is found.
|
Below is an example when using ENOVIA/Basic authentication and how such might look like.
Note that in this example, each user that is supposed to use the web-services must have the role "WS-Integration-User". Note that depending on login service used (ldap or enovia), the role is either a LDAP role or a ENOVIA role.
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>WS-Integration-User</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
Below is an example for Spnego:
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>EXAMPLEDOMAIN.COM</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>SPNEGO</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
TIF allows deploying custom SOAP Webservice’s.
If you have built a Webservice and packaged it as an AAR file, you can simply drop your AAR file with in the directory:
${TIF_ROOT}/modules/enovia/webapps/jaxws/WEB-INF/services
These services are then automatically deployed during startup.
It is also possible host web services that are implemented by JSR 181 annotated Java classes.
The web service classes needs to be compiled with the help of the Apache Axis2 libs in to a JAR file.
The web service is deployed by dropping the compiled JAR file into ${TIF_ROOT}/modules/enovia/webapps/jaxws/WEB-INF/servicejars
.
For example:
package com.acme.tif;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
@SOAPBinding(style = SOAPBinding.Style.RPC)
@WebService(serviceName = "MyWebService", targetNamespace = "http://technia.com")
public class MyWebService {
@WebMethod(operationName = "myMethod")
public String myMethod(@WebParam(name = "yourString") String yourString) {
return yourString + " received";
}
}
An alternative to use Apache Axis and AAR files, is to use Apache CXF and host the CXF application inside TIF.
You deploy custom webapps by creating a new folder below ${TIF_ROOT}/modules/enovia/webapps
.
By default, the URL to such webapp is following this format
http://hostname:8181/enovia/name-of-folder/...
Note that you can customize the context path per webapp via ${TIF_ROOT}/modules/enovia/etc/module.custome.properties
.
There is a Apache CXF base webapp under ${TIF_ROOT}/modules/enovia/webapps/cxf
that can be used as base/template for CXF based web services.
There are own servlet filters for SOAP and RESTFul web services that can be used for logging web service calls to TIF DB. See web.xml
for filter details. Also, there is cxf-servlet.xml
that contains configurations for example web services.
If you have not started TIF, you will not find the web.xml or cxf-template.xml file, instead there are template files. Upon start, TIF will copy over the template file unless the web.xml or cxf-template.xml file is found. |
Hosted SOAP web service is automatically logged in the TIF database. It appears as a SOAP service in Admin UI.
For example, http://localhost:8181/enovia/jaxws/services/myService
is visible in Admin UI as "myService" SOAP service.
There are configurable webapp init parameters to set maximum length for logged inbound (request) and outbound (response) payloads. Parameters help to limit usage of heap memory and storage by preventing to persist too large payloads to TIF DB.
See parameters "inboundPayloadMaxLength" and "outboundPayloadMaxLength" in web.xml
.
Default value for parameters is 1 000 000 bytes, if not defined. |
Some legacy systems communicate with each other by creating files in certain directories in the file system. TIF provides built-in support for setting up one or several listeners that will listen to changes in a directory (or directories) in the file-system and then perform some action.
You can listen to events in the file system like CREATE or MODIFY. By default, a directory listener will react upon the CREATE event.
When a directory listener receives an event, the processing of the file will take place a few moments later according to the configured pickup-delay (default is 3000 ms.). This pickup delay will ensure that we do not react upon multiple events for the same file, which may be the case on some Operating Systems (Windows using file-shares for example).
You can set-up several directory listeners, each will then listen to different directories within the file-system.
Do not configure multiple listeners that will listen to the same or a sub-directory as another directory listeners is configured for. |
The preferred way of configuring such listener is to use the XML configuration format.
E.g. adding a file within the directory ${TIF_ROOT}/modules/enovia/cfg/directorylistener
.
By default, this directory is scanned upon startup and all configured listeners therein will be registered automatically.
You can configure this behaviour within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
via the following properties:
Property | Type | Default | Description |
---|---|---|---|
resources.directorylistener.autoRegister |
boolean |
True |
Use this property to disable the auto registration |
resources.directorylistener.excluded |
Comma separated list |
Comma separated list of resources to be excluded. |
|
resources.directorylistener.included |
Comma separated list |
Comma separated list of resources to be included. |
By default, auto registration is enabled and no resources are excluded.
The root element is <DirectoryListener>
. The table below lists the allowed child elements:
Element | Required | Description | Example |
---|---|---|---|
|
Yes |
Defines a user friendly name of this configuration |
|
|
No |
Defines the pickup delay in milliseconds. Default is 3000. |
|
|
No |
Can be used to define a File Destination that defines the directory where to listen from. Either this is defined OR the |
|
|
Yes, unless a |
Defines input/output/error paths. |
See below. |
|
No |
Define file system events to react upon. Default is CREATE event only. |
|
No |
Defines if to establish an ENOVIA context |
|
|
Yes |
Defines the handler containing your businesslogic that is processing the message |
|
|
The <Paths>
element supports the following attributes.
A boolean specifying if to register to sub-directories also. Default is true
A boolean specifying if to process files in the input directory upon startup. Default is true.
A boolean specifying if to register new directories created within the monitored file-area. Default is true.
Whether or not to delete the file after it has been processed.
If donePath and/or errorPath has been set then the file is moved instead of being deleted, even if delete flag is set to true.
|
The <Paths>
element supports the following child elements.
Element | Required | Description | Example |
---|---|---|---|
|
Yes |
Defines input directory. Use multiple |
|
|
No |
Defines a directory, which files are moved to upon successful processing |
|
|
No |
Defines a directory, which files are moved to upon an error |
|
The <Events>
element supports the following child elements.
Element | Required | Description |
---|---|---|
|
No |
React upon create events |
|
No |
React upon modify events |
|
No |
React upon delete events |
Leaving the Events out implies reacting upon Create events. |
The <WithContext>
element supports the following attributes.
Attribute | Required | Description |
---|---|---|
user |
No |
If omitted, the super user will be used |
securityContext |
No |
Defines the security context to be used |
useDefaultSecurityContext |
No |
If set to true, the default security context for the user will be used. The used user must have a default security context otherwise an error will be raised. |
The <Handler>
element supports one of these three attributes
The name of a class implementing com.technia.tif.enovia.file.WatcherHandler
. See chapter below.
Name of a script resource. Example: script="tvc:script/MyHandler.js"
. See chapter below.
Name of a pre-defined type. Example: type="SomePredefinedType"
Example configuration:
<tif:DirectoryListener
xmlns:tif="http://technia.com/TIF/DirectoryListener"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://technia.com/TIF/DirectoryListener file:///C:/apps/tif-server/modules/enovia/schema/DirectoryListener.xsd">
<tif:Name>Test Listener</tif:Name>
<tif:Paths>
<tif:Input>/test/a/input</tif:Input>
<tif:Output>/test/a/done</tif:Output>
<tif:Error>/test/a/error</tif:Error>
</tif:Paths>
<tif:WithContext />
<tif:Handler className="com.acme.integrations.part.DefaultMessageReceiver" />
</tif:AMQPListener>
You can change a definition at runtime, but you need to restart the corresponding service activator from within the Administration UI in order to pick up the changes. |
The recommended way of registering a directory listener is to use the XML configuration format as described in the previous chapter.
However, you may still register a listener from with the module properties file. E.g. using the file
${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
Below is an example configuration:
directoryListener.0.enabled = true
directoryListener.0.name = A User Friendly Name
directoryListener.0.directories = /var/integration/erp
directoryListener.0.recurse = true
directoryListener.0.className = com.acme.integrations.ERPDirectoryListener
directoryListener.0.context = true
directoryListener.0.context.user = ...
directoryListener.0.context.securityContext = ..
directoryListener.0.context.useDefaultSecurityContext = true|false
The prefix of a directory listener is directoryListener.<ID>.
where <ID>
is a unique identifier containing letters and/or digits.
The available property suffices are shown in the table below.
Property Suffix | Description | Required | Default |
---|---|---|---|
name |
Defines a user friendly name of the service, used for example in the Admin UI |
No |
Default the name is equal to the ID |
enabled |
Defines if the directory listener should be enabled or not. |
No |
True |
directories |
The directories to listen for changes in. Use ";" (semi-colon) on Windows to separate multiple directories and ":" (colon) on UNIX. |
Yes |
|
recurse |
Whether or not if to recursively listen to changes in directories below the specified. |
No |
True |
deleteFile |
Whether or not to delete the file after it has been processed. Note that if the |
No |
False |
donePath |
Specifies a directory, to which successfully processed files will be moved into |
No |
|
errorPath |
Specifies a directory, to which processed files that failed will be moved into |
No |
|
events |
Specifies a comma separated list of events that we should react upon. Possible values are
|
No |
create |
pickupDelay |
Specifies the delay in milliseconds to delay the processing of the file |
No |
3000 |
processExistingOnStartup |
Specifies if to process existing files in the directories we watch upon startup. Note that this flag should not be set to true in case you choose to NOT delete the files nor move it after processing. Otherwise the same files will be processed every time you start TIF, or restart the particular service. |
No |
True |
registerNewDirectories |
Specifies if to register new directories being added as being watched. Note that this will only have effect if also the recurse flag is set to true. |
No |
True |
context |
A boolean value indicating if an ENOVIA context object should be allocated when the handler is invoked. |
No. |
False. |
context.user |
An optional name of a ENOVIA user (used if context = true). May be omitted to indicate that the default ENOVIA system-user should be used. |
No |
Defaults to the system user. |
context.securityContext |
Specify ENOVIA securtity context. |
No |
|
context.useDefaultSecurityContext |
Specify to use the default securtity context on the user. |
No |
False |
className |
Defines a fully qualified class name of a Java class implementing "com.technia.tif.enovia.file.WatcherHandler". See below. |
One of the attributes |
|
script |
A script that implements the same functionality as a corresponding Java class. See below. |
Example registration:
directoryListener.0.enabled = true
directoryListener.0.directories = /var/integration/erp
directoryListener.0.recurse = false
directoryListener.0.context = true
directoryListener.0.donePath = /var/integration/erp/succeeded
directoryListener.0.errorPath = /var/integration/erp/failed
directoryListener.0.className = com.acme.tif.FileProcessor
The Java class pointed out via the className attribute must implement the interface com.technia.tif.enovia.file.WatcherHandler
in TIF. This Watcher-Handler API looks like:
package com.technia.tif.enovia.file;
import java.nio.file.Path;
/**
* @author Technia
*/
public interface WatcherHandler {
/**
* @param event The event causing this call
* @param p The path
*/
void handleEvent(WatchEvent event, Path p);
}
The first argument to the "handleEvent" is an enum instance, which may have the following values:
WatchEvent.CREATE WatchEvent.MODIFY WatchEvent.DELETE
Instead of implementing the WatcherHandler as a traditional Java class you may implement this in a script file.
Scripts are stored and handled as a XML resource file, described in chapter [XXX].
Example:
directoryListener.TEST.script = DirectoryListener.js
or
directoryListener.TEST.script = tvc:script/DirectoryListener.js
or
directoryListener.TEST.script = tvc:script:domain/DirectoryListener.js
A directory listener implemented as a script has the same method signature as the corresponding Java-class implementation.
function handleEvent(type, path) {
if (type == "CREATE") {
} else if (type == "DELETE") {
} else if (type == "MODIFY") {
}
}
The last argument is an object of type java.nio.file.Path
You may want to listen to a JMS queue or topic from TIF. This page describes how to set-up a so called JMS Message Receiver in TIF.
You can set-up several JMS listeners, each will then listen to different queues or topics.
The preferred way of configuring such listener is to use the XML configuration format.
E.g. adding a file within the directory ${TIF_ROOT}/modules/enovia/cfg/jmslistener
.
By default, this directory is scanned upon startup and all configured listeners therein will be registered automatically.
You can configure this behavior within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
via the following properties:
Property | Type | Default | Description |
---|---|---|---|
resources.jmsListener.autoRegister |
boolean |
True |
Use this property to disable the auto registration |
resources.jmsListener.excluded |
Comma separated list |
Comma separated list of resources to be excluded. |
|
resources.jmsListener.included |
Comma separated list |
Comma separated list of resources to be included. |
By default, auto registration is enabled and no resources are excluded.
The root element is <JMSListener>
. The table below lists the allowed child elements
Element | Required | Description | Example |
---|---|---|---|
|
Yes |
Defines a user friendly name of this configuration |
|
|
Yes |
Defines what destination to listen from |
|
|
No |
Defines if to establish an ENOVIA context |
|
|
Yes |
Defines the handler containing your businesslogic that is processing the message |
|
|
No |
Can be used to specify a selector, which then will limit the messages based upon the criteria in the selector. |
|
|
No |
Defines number of concurrent consumers. Typically used with destination listening to a queue. |
|
|
No |
Boolean defining if to share connection per destination with other JMS listeners. The common default value can be configured with property |
|
|
Yes |
Defines a user friendly name of this configuration |
|
The <WithContext>
element supports the following attributes.
Attribute | Required | Description |
---|---|---|
user |
No |
If omitted, the super user will be used |
securityContext |
No |
Defines the security context to be used |
useDefaultSecurityContext |
No |
If set to true, the default security context for the user will be used. The used user must have a default security context otherwise an error will be raised. |
The <Handler>
element supports one of these three attributes
The name of a class implementing com.technia.tif.enovia.jms.MessageReceiver
. See chapter below.
Name of a script resource. Example: script="tvc:script/MyMessageReceiver.js"
. See chapter below.
Name of a pre-defined type. Example: type="SomePredefinedType"
Example configuration:
<tif:JMSListener
xmlns:tif="http://technia.com/TIF/JMSListener"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://technia.com/TIF/JMSListener file:///C:/apps/tif-server/modules/enovia/schema/JMSListener.xsd">
<tif:Name>Test Listener</tif:Name>
<tif:Destination id="part-from-erp" />
<tif:WithContext />
<tif:Handler className="com.acme.integrations.part.DefaultMessageReceiver" />
</tif:JMSListener>
You can change a definition at runtime, but you need to restart the corresponding service activator from within the Administration UI in order to pick up the changes. |
Currently, there is no support for adding new or deleting existing definitions at runtime. Such change requires a restart of the TIF server in order to reflect the new state. |
Too high consumer count will result in performance degradation. |
The recommended way of registering a JMS listener is to use the XML configuration format as described in the previous chapter.
However, you may still register a listener from with the module properties file. E.g. using the file
${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
Below is an example configuration:
jmsListener.0.enabled = true jmsListener.0.className = com.technia.tif.enovia.jms.TestReceiver jmsListener.0.destination = jms-1 jmsListener.0.context = true jmsListener.0.name = Service Name
The prefix of a JMS listener is jmsListener.<ID>.
where <ID>
is a unique identifier containing only letters and/or digits.
The available property suffices are shown in the table below.
Property Suffix | Description | Required |
---|---|---|
enabled |
Defines if the directory listener should be enabled or not. |
No. Default is true |
destination |
The ID of a JMS destination defined in the "destination.xml" file. See Configure Destinations for details how to register destinations. |
Yes |
context |
A boolean value indicating if an ENOVIA context object should be allocated when the message receiver is invoked. |
No. Default is false. |
context.user |
An optional name of a ENOVIA™ user (used if context = true). May be omitted to indicate that the default ENOVIA system-user should be used. |
No. Defaults to the system user. |
context.securityContext |
Specify ENOVIA securtity context. |
No |
context.useDefaultSecurityContext |
Specify to use the default securtity context on the user. |
No |
name |
Name of the service. Used in the Admin UI. |
No. |
messageSelector |
Optional string used for selecting messages. See this page for additional information. |
No. |
className |
Defines a fully qualified class name of a Java class either:
See below. |
One of the attributes className or script must be defined. |
script |
A script that implements the same functionality as a corresponding Java class. See below. |
The Java class pointed out via the className
attribute must implement the interface MessageReceiver in TIF. This API looks like:
package com.technia.tif.enovia.jms;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.Session;
import com.technia.tif.core.annotation.API;
/**
*
* @author Technia
* @since 2 maj 2013
*/
@API
public interface MessageReceiver {
/**
* Called prior to the JMS connection and session is closed. Note that there
* is no guarantee that this method is invoked, however, you can implement
* this method if you need to release any resource you have opened.
*/
void close();
/**
* @return True if to use transactions.
*/
boolean isTransacted();
/**
* @return The acknowledgemode. Must be any of the integer constants defined
* in the Session class.
*/
int getAcknowledgeMode();
/**
* Called when a new message appears.
*
* @param message The message to handle
* @throws Exception
*/
void onMessage(Message message) throws Exception;
/**
* If an exception occurs, this method is called.
*
* @param exception The JMS exception
*/
void onException(JMSException exception);
/**
* Called upon creation of a response message.
*
* @param session
* @param message
* @return
* @throws JMSException
* @since 2015.3.0
*/
Message createResponseMessage(Session session, Message message) throws JMSException;
}
For convenience, there is an adapter class available called com.technia.tif.enovia.jms.MessageReceiverAdapter
that can be used instead. This adapter class only has one abstract method, namely "onMessage". This adapter class returns false for the "isTransacted" and "Session.AUTO_ACKNOWLEDGE" for the acknowledge mode as default.
For incoming messages that has a replyTo destination set, TIF will call the createResponseMessage method, which allows you to create the proper message to be re-delivered back to the sender.
|
Instead of implementing the MessageReceiver as a traditional Java class you may implement this in a script file.
Scripts are stored and handled as a XML resource file, described at [XXX].
Examples:
jmsListener.TEST.script = JMSListener.js (1) jmsListener.TEST.script = tvc:script/JMSListener.js (2) jmsListener.TEST.script = tvc:script:domain/JMSListener.js (3)
1 | refers to the file cfg/script/JMSListener.js |
2 | refers to the file cfg/script/JMSListener.js |
3 | refers to the file cfg/domain/script/JMSListener.js |
The script you write must as a minimum implement the "onMessage" method, and you may implement the others defined in the interface. The default value for "isTransacted" is FALSE and "Session.AUTO_ACKNOWLEDGE" for the "acknowledge mode".
Example:
function onMessage(msg) {
// do something
}
function isTransacted() {
return false;
}
You may want to receive messages from a Rabbit MQ message broker. This page describes how to set-up a so called RabbitMQ Message Receiver in TIF allowing you to do so.
You can set-up several RabbitMQ listeners, each will then listen to different queues or topics.
The preferred way of configuring such listener is to use the XML configuration format.
E.g. adding a file within the directory ${TIF_ROOT}/modules/enovia/cfg/rabbitmqlistener
.
By default, this directory is scanned upon start-up and all configured listeners therein will be registered automatically.
You can configure this behaviour within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
via the following properties:
Property | Type | Default | Description |
---|---|---|---|
resources.rabbitmqlistener.autoRegister |
boolean |
True |
Use this property to disable the auto registration |
resources.rabbitmqlistener.excluded |
Comma separated list |
Comma separated list of resources to be excluded. |
|
resources.rabbitmqlistener.included |
Comma separated list |
Comma separated list of resources to be included. |
By default, auto registration is enabled and no resources are excluded.
The root element is <AMQPListener>
. The table below lists the allowed child elements
Element | Required | Description | Example |
---|---|---|---|
|
Yes |
Defines a user friendly name of this configuration |
|
|
Yes |
Defines what destination to listen from |
|
|
No |
Defines if to establish an ENOVIA context |
|
|
Yes |
Defines the handler containing your businesslogic that is processing the message |
|
|
No |
Some handlers might accept arguments. |
|
The <WithContext>
element supports the following attributes.
Attribute | Required | Description |
---|---|---|
user |
No |
If omitted, the super user will be used |
securityContext |
No |
Defines the security context to be used |
useDefaultSecurityContext |
No |
If set to true, the default security context for the user will be used. The used user must have a default security context otherwise an error will be raised. |
The <Handler>
element supports one of these three attributes
The name of a class implementing com.technia.tif.enovia.rabbitmq.MessageReceiver
. See chapter below.
Name of a script resource. Example: script="tvc:script/MyMessageReceiver.js"
. See chapter below.
Name of a pre-defined type. Example: type="SomePredefinedType"
Example configuration:
<tif:AMQPListener
xmlns:tif="http://technia.com/TIF/AMQPListener"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://technia.com/TIF/AMQPListener file:///C:/apps/tif-server/modules/enovia/schema/AMQPListener.xsd">
<tif:Name>Test Listener</tif:Name>
<tif:Destination id="part-from-erp" />
<tif:WithContext />
<tif:Handler className="com.acme.integrations.part.DefaultMessageReceiver" />
</tif:AMQPListener>
You can change a definition at runtime, but you need to restart the corresponding service activator from within the Administration UI in order to pick up the changes. |
Currently, there is no support for adding new or deleting existing definitions at runtime. Such change requires a restart of the TIF server in order to reflect the new state. |
The recommended way of registering a Rabbit-MQ listener is to use the XML configuration format as described in the previous chapter.
However, you may still register a listener from with the module properties file.
E.g. using the file ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
Below is an example configuration:
rabbitmqListener.0.enabled = true rabbitmqListener.0.className = com.technia.tif.enovia.rabbitmq.TestReceiver rabbitmqListener.0.destination = rabbitmq-1 rabbitmqListener.0.context = true rabbitmqListener.0.name = Service Name
The prefix of a RabbitMQ listener is rabbitmqListener.<ID>.
where <ID>
is a unique identifier containing only letters and/or digits.
The available property suffices are shown in the table below.
Property Suffix | Description | Required |
---|---|---|
enabled |
Defines if the directory listener should be enabled or not. |
No. Default is true |
destination |
The ID of a RabbitMQ destination defined in the "destination.xml" file. See Configure Destinations for details how to register destinations. |
Yes |
context |
A boolean value indicating if an ENOVIA context object should be allocated when the message receiver is invoked. |
No. Default is false. |
context.user |
An optional name of a ENOVIA™ user (used if context = true). May be omitted to indicate that the default ENOVIA system-user should be used. |
No. Defaults to the system user. |
context.securityContext |
Specify ENOVIA securtity context. |
No |
context.useDefaultSecurityContext |
Specify to use the default securtity context on the user. |
No |
name |
Name of the service. Used in the Admin UI. |
No. |
className |
Defines a fully qualified class name of a Java class that implements "com.technia.tif.enovia.rabbitmq.MessageReceiver". See below. |
One of the attributes className or script must be defined. |
script |
A script that implements the same functionality as a corresponding Java class. See below. |
The Java class pointed out via the className
attribute must implement the interface MessageReceiver in TIF. This API looks like:
package com.technia.tif.enovia.rabbitmq;
/**
* This interface must be implemented to handle messages received by RabbitMQ
* listener.
*
* @since 2015.3.0 Initial version
* @since 2020.2.0 Refactored to support better message control
*/
public interface MessageReceiver {
/**
* Called when a new message appears.
*
* @param msg The message to handle
* @return The result of the operation. Depending on the result, the message
* will either be acknowledged (with multiple flag set or not),
* not-acknowledged (rejected) (with multiple flag set or not) or
* nothing is done.
* @throws Exception If a failure occurs.
*/
Result onMessage(Message msg) throws Exception;
/**
* If an exception occurs, this method is called. The default implementation
* does nothing and returns a {@link Result#NACK} value.
*
* @param e The exception
* @param msg The message
*/
default Result onException(Exception e, Message msg) {
return Result.NACK;
}
}
The return value enum constants are described below.
Do nothing
Acknowledges the current message
Rejects the current message
Rejects the current message and requeues it
Acknowledges multiple messages, e.g. all messages that have not yet been ack/nack’ed
Rejects multiple messages.
Rejects multiple messages and requeues all.
Instead of implementing the MessageReceiver as a traditional Java class you may implement this in a script file.
Scripts are stored and handled similar to any other configuration resource file, e.g. below the cfg folder.
The scripts goes into the folder script
, e.g. ${TIF_HOME}/modules/enovia/cfg/script
.
You may also use domains, as for the other configuration files. See below:
Examples:
rabbitmqListener.TEST.script = RabbitMQListener.js (1) rabbitmqListener.TEST.script = tvc:script/RabbitMQListener.js (2) rabbitmqListener.TEST.script = tvc:script:domain/RabbitMQListener.js (3)
1 | refers to the file cfg/script/RabbitMQListener.js |
2 | refers to the file cfg/script/RabbitMQListener.js |
3 | refers to the file cfg/domain/script/RabbitMQListener.js |
The script you write must implement "onMessage" and "onException" methods.
Example:
function onMessage(msg) {
// Logic goes here.
return com.technia.tif.enovia.rabbitmq.Result.ACK;
}
//Override if needed to handle exception
//function onException(e, msg) {
//
// return com.technia.tif.enovia.rabbitmq.Result.NACK;
//}
You may want to listen for messages from a IBM MQ queue from TIF. This page describes how to set-up a so called IBM-MQ/NativeMQ/WebsphereMQ Message Listener in TIF.
You can set-up several MQ listeners, each will then listen to different queues or topics.
The preferred way of configuring such listener is to use the XML configuration format.
E.g. adding a file within the directory ${TIF_ROOT}/modules/enovia/cfg/mqlistener
.
By default, this directory is scanned upon startup and all configured listeners therein will be registered automatically.
You can configure this behavior within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
via the following properties:
Property | Type | Default | Description |
---|---|---|---|
resources.mqlistener.autoRegister |
boolean |
True |
Use this property to disable the auto registration |
resources.mqlistener.excluded |
Comma separated list |
Comma separated list of resources to be excluded. |
|
resources.mqlistener.included |
Comma separated list |
Comma separated list of resources to be included. |
By default, auto registration is enabled and no resources are excluded.
The root element is <MQListener>
. The table below lists the allowed child elements
Element | Required | Description | Example |
---|---|---|---|
|
Yes |
Defines a user friendly name of this configuration |
|
|
Yes |
Defines what destination to listen from |
|
|
No |
Defines if to establish an ENOVIA context |
|
|
Yes |
Defines the handler containing your businesslogic that is processing the message |
|
|
No |
Some handlers might accept arguments. |
|
The <WithContext>
element supports the following attributes.
Attribute | Required | Description |
---|---|---|
user |
No |
If omitted, the super user will be used |
securityContext |
No |
Defines the security context to be used |
useDefaultSecurityContext |
No |
If set to true, the default security context for the user will be used. The used user must have a default security context otherwise an error will be raised. |
The <Handler>
element supports one of these three attributes
The name of a class implementing com.technia.tif.enovia.nativemq.MessageReceiver
. See chapter below.
Name of a script resource. Example: script="tvc:script/MyMessageReceiver.js"
. See chapter below.
Name of a pre-defined type. Example: type="SomePredefinedType"
Example configuration:
<tif:MQListener
xmlns:tif="http://technia.com/TIF/MQListener"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://technia.com/TIF/MQListener file:///C:/apps/tif-server/modules/enovia/schema/MQListener.xsd">
<tif:Name>Test Listener</tif:Name>
<tif:Destination id="part-from-erp" />
<tif:WithContext />
<tif:Handler className="com.acme.integrations.part.DefaultMessageReceiver" />
</tif:MQListener>
You can change a definition at runtime, but you need to restart the corresponding service activator from within the Administration UI in order to pick up the changes. |
Currently, there is no support for adding new or deleting existing definitions at runtime. Such change requires a restart of the TIF server in order to reflect the new state. |
The recommended way of registering a Rabbit-MQ listener is to use the XML configuration format as described in the previous chapter.
However, you may still register a listener from with the module properties file. E.g. using the file
${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
This is configured within the "module.properties" file within the etc folder. See page this page for details how to modify this file.
Below is an example configuration:
wmqListener.0.enabled = true wmqListener.0.className = com.technia.tif.enovia.nativemq.TestReceiver wmqListener.0.destination = mq-1 wmqListener.0.context = true wmqListener.0.name = Service Name
The prefix of a MQ listener is wmqListener.<NAME>.
where <NAME>
is a unique name containing only letters and/or digits.
The available property suffices are shown in the table below.
Property Suffix | Description | Required |
---|---|---|
enabled |
Defines if the directory listener should be enabled or not. |
No. Default is true |
destination |
The ID of a NativeMQ destination defined in the "destination.xml" file. See Configure Destinations for details how to register destinations. |
Yes |
context |
A boolean value indicating if an ENOVIA context object should be allocated when the message receiver is invoked. |
No. Default is false. |
context.user |
An optional name of a ENOVIA™ user (used if context = true). May be omitted to indicate that the default ENOVIA system-user should be used. |
No. Defaults to the system user. |
context.securityContext |
Specify ENOVIA securtity context. |
No |
context.useDefaultSecurityContext |
Specify to use the default securtity context on the user. |
No |
name |
Name of the service. Used in the Admin UI. |
No. |
className |
Defines a fully qualified class name of a Java class that implements |
One of the attributes className or script must be defined. |
script |
A script that implements the same functionality as a corresponding Java class. See below. |
The Java class pointed out via the className
attribute must either
implement the interface com.technia.tif.enovia.nativemq.MessageReceiver
or extend the class com.technia.tif.enovia.nativemq.MessageReceiverAdapter
.
Example skeleton below:
import com.ibm.mq.MQMessage;
public class TestReceiver extends MessageReceiverAdapter {
@Override
public void onMessage(MQMessage message) {
}
}
Instead of implementing the MessageReceiver as a traditional Java class you may implement this in a script file.
Scripts are stored and handled as a XML resource file, described at [XXX].
Examples:
wmqListener.TEST.script = MQListener.js (1) wmqListener.TEST.script = tvc:script/MQListener.js (2) wmqListener.TEST.script = tvc:script:domain/MQListener.js (3)
1 | refers to the file cfg/script/MQListener.js |
2 | refers to the file cfg/script/MQListener.js |
3 | refers to the file cfg/domain/script/MQListener.js |
The script you write must implement at least the "onMessage" method.
Example:
function onMessage(msg) {
// do something
}
RESTful web services are created with XML configuration files. The services are used to expose information available in ENOVIA.
The base URL for services are (by default):
http://server:8181/enovia/jaxrs/service
The example above uses the default context path /enovia/jaxrs. This path may be different in your environment since it can be configured. See the next chapter for more information how to change this. |
A list of available services can be retrieved by accessing the base URL. Services are listed in JSON format. Example using cUrl:
curl -X GET http://server:8181/enovia/jaxrs/service
Every service has a unique service name which is used when accessing it.
For example, a service with the name part
is available on:
http://server:8181/enovia/jaxrs/service/part
Any information after the service name in the URL is interpreted as PathParameters. Example of URL using PathParameters:
http://server:8181/enovia/jaxrs/service/part/Resistor/1200-0001/1
By default, the context path to the REST applications is /enovia/jaxrs/.
Within the file ${TIF_ROOT}/modules/enovia/etc/modules.custom.properties
,
this can be changed using the property below.
http.webapp.jaxrs.contextPath = /enovia/jaxrs ^^^^^
As an alternative you could also change the path for all applications by using the below example.
http.webapp.contextPath.default = /tif/%2$s
The %2$s
refers to the name of the webapp folder.
<Rest>
<DisplayName>Part</DisplayName>
<ServiceName>part</ServiceName>
<IdLocator type="tnr">
<AllowWildcards>false</AllowWildcards>
</IdLocator>
<Read payload="tvc:payload:tix/PartData.xml" />
<Events>...</Events>
</Rest>
Configuration files are stored in the folder restservice
. The root element of
the XML file is <Rest>
. The available child elements are listed in the table
below.
Element | Description | Mandatory |
---|---|---|
|
User friendly name of the service. Used for instance the Admin UI. |
No, but recommended. |
|
Defines the name of the service. It is used by clients to access the service. The name must be unique across all services. It may only consist of alfanumerical characters and forward slashes (/). |
No |
Defines how to find the object/s the client is interested in. Read more in the IdLocator chapter. |
No |
|
Defines how to read data. Read more in the Read Operation chapter. |
Yes |
|
See page Job Events for details. |
No |
|
Defines the credentials that will be used when running the REST service. Read more in the Credentials chapter. |
Yes. |
|
|
Defines the type of transaction to use while running the REST service. The possible values are:
|
No. An inactive (no transaction) is used. |
|
May be used to define additional access rules on the REST service. Example; only allow this REST service to operate on objects in a particular state, or in a particular vault. Or, restrict access to users assigned to a particular role or group. Read more in the Access chapter. |
No. |
If the <ServiceName>
element is omitted, the name of the service is calculated based on its location in the filesystem.
For example, if a RestService is stored in the folder cfg/restservice/foo/bar/test.xml
then its service name / path is calculated to foo/bar/test
.
And in case a RestService is stored in the folder cfg/restservice/part-data.xml
then its service name / path is calculated to part-data
.
Client sends HTTP request. The request include information about which service that is of interest along with addtional PathParameters/QueryParamters.
The RESTful web services corresponding to the request is located. TIF maintains a registry of all configurable services.
Optional: The IdLocator is executed. It is responsible for finding the object the client is requesting based on the PathParamters/QueryParameters.
The operation is executed. For example, extracting information for the Part found by the IdLocator.
The response is sent back to the client.
The <Credentials>
element contains the following attributes:
A boolean value. Specifies if authentication is carried out via the servlet container. See chapter below how to configure this.
A string value. Defines the name of the ENOVIA™ user that we will run the service as.
A boolean value. Useful together when containerManaged=true
and
you want to run the service as a super user, while authentication is required.
Valid child elements are defined in the table below
Element | Description | Mandatory |
---|---|---|
|
Used for defining the ENOVIA/3DExperience security context. See below how to configure this. |
No |
|
In case container managed authentication is enabled, you may define additional roles, which the authenticated user must have in order to gain access. These roles are typically not ENOVIA/3DExperience roles, in case of Kerberos authentication these will be roles from your Active Directory. Note that if you specify multiple roles, the user is only required to have one of the listed roles in order to get access. Example below:
|
No. |
|
Specify additional ENOVIA/3DExperience assignments the user must have in order to proceed. Example below:
|
No |
Via the <SecurityContext>
element you define what security context to use.
You may do the following.
Point out a mapping file
Or use a default mapping file
Specify a named security context
Or use the "default" security context as configured for the ENOVIA user
To point out a mapFile use the syntax below.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext mapFile="sec-mapping.xml" />
Use the default mapping file.
The default file is specified via the property securityMapping.defaultFile
, and the default value is security-context-mapping.xml
.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext useDefaultMapFile="true" />
The format of the mapping file is shown below:
<Contexts>
<Context name="Design Engineer.Company Name.GLOBAL">
<User is="user1" />(1)
<User is="user2" />
<User is="user3" />
<Role is="engineer" /> (2)
<Role is="designer" />
<Parameter name="test" is="something" /> (3)
<Parameter name="x" is="y" />
</Context>
<Context name="...">...</Context>
<Context name="...">...</Context>
</Contexts>
NOTE that specifying user and role requires having enabled container managed authentication (Kerberos or Basic Authenticaton etc.)
1 | Specifies certain users to match against |
2 | Specifies additional roles the user should have |
3 | Specifies additional parameters and value to be evaluated In case of a REST service, the parameters are the request parameters passed to the service. |
The evaluation logic is:
User list is EMPTY or user is in list
Role list is EMPTY or user have one of the roles in the list
Parameter list is EMPTY or one of the parameters have the expected value
If A AND B AND C is satisfied, then use the security context defined for this "rule".
To use a specific Security Context:
<SecurityContext use="Design Engineer.Company Name.GLOBAL" />
Specify using the default security context.
<SecurityContext useDefault="true" />
You can enable security on the servlet container level and either use Kerberos/SPNego authentication OR use Basic authentication and authenticate against the ENOVIA™ database.
Within the ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
, you need
to specify what login service to be used including its realm and optionally some
extra parameters.
The login services currently supported are
A login service that will authenticate the remote user against the ENOVIA™ database.
A login service that will authenticate the remote user against a LDAP directory (for example Active Directory)
A login service supporting Single Sign On against Active Directory.
In order to use Spnego authentication, also read this document in order to setup the core parts of Spnego/Kerberos. |
If the "loginService" is set to "ldap", TIF will authenticate users against a LDAP directory.
http.webapp.jaxrs.loginService=ldap
http.webapp.jaxrs.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
There are some additional LDAP settings required to be defined. You can specify global LDAP parameters and/or web application specific LDAP parameters. In most cases you will be fine with only global LDAP settings.
For convenience, the application specific parameters will be merged with the global LDAP parameters. Hence you only need to override/define the parameters that is different on the application level.
Please see the table below.
The global parameter name is ldap. , while the application specific parameter
are named like http.webapp.<APP_NAME>.ldap.
|
Parameter | Description | Required |
---|---|---|
ldap.server |
Defines the server or list of LDAP servers. Separate with space if using multiple. |
Yes |
ldap.rootDN |
Defines the root dn, where all LDAP searches starts from. If we can start a search starting at a sub-node (as opposed to root), you get a better performance because it narrows down the scope of a search. This field specifies the DN of such a subtree. |
No |
ldap.userSearchBase |
The relative DN (From the root DN) that further narrow down searches to the sub-tree. If you do specify this value, the field normally looks something like "ou=people". |
No |
ldap.userSearchFilter |
This field determines the query to be run to identify the user record. The query is almost always "uid={0}" as per defined in RFC 2798, so in most cases you should leave this field empty and let this default kick in. If your LDAP server doesn’t have uid or doesn’t use a meaningful uid value, try "mail={0}", which lets people login by their e-mail address. If you do specify a different query, specify an LDAP query string with marker token "{0}", which is to be replaced by the user name string entered by the user. |
Yes |
ldap.groupMembershipAttribute |
If the user entry in the LDAP tree contains an attribute with the group membership, then specify that attribute here. Otherwise we need to query for the groups a user belongs to. |
Either this or the groupSearchBase / groupSearchFilter needs to be defined. |
ldap.groupSearchBase |
This field determines the query to be run to identify the organizational unit that contains groups. The query is almost always "ou=groups" so try that first, though this field may be left blank to search from the root DN. |
Not needed, but if the groupMembershipAttribute is undefine you can use this to make the group query faster. |
ldap.groupSearchFilter |
Defines the search filter for groups. In case we need to search the LDAP tree for group membership this needs to be defined. The marker token "{0}" is replaced with the current user’s DN. Example:
|
Yes unless groupMembershipAttribute is defined. |
ldap.managerDN |
If your LDAP server doesn’t support anonymous binding, then we would have to first authenticate itself against the LDAP server. A DN typically looks like CN=MyUser,CN=Users,DC=mydomain,DC=com although the exact sequence of tokens depends on the LDAP server configuration. It can be any valid DN as long as LDAP allows this user to query data. |
Probably Yes |
ldap.managerSecret |
The password for the manager DN |
Probably Yes |
ldap.displayNameLDAPAttribute |
The attribute holding the display name. Per default we use the CN of the user entry. |
No |
ldap.emailAddressLDAPAttribute |
The attribute holding the email value. Per default we use the field This field is currently not used so you can leave it blank. |
No |
ldap.pooled |
Whether or not to pool the LDAP connections |
No |
Example setup below for Active Directory.
ldap.server=ldapserver.yourdomain.com:3268
ldap.rootDN=DC=yourdomain,DC=com
ldap.managerDN=CN=nameofuser,CN=groupforuser,DC=yourdomain,DC=com
ldap.managerSecret=the_very_secret_string
ldap.userSearchBase=
ldap.userSearchFilter=(&(objectClass=person)(|(sAMAccountName={0})(userPrincipalName={0}@*)))
ldap.emailAddressLDAPAttribute=mail
ldap.displayNameLDAPAttribute=displayName
ldap.groupMembershipAttribute=memberOf
#ldap.groupSearchBase=OU=groups
#ldap.groupSearchFilter=(&(member={0})(objectClass=group))
The managerSecret value can either be defined in plain text, or you can encrypt the password from an MQL client using the "mql encrypt" feature.
The encrypted value can be used in the configuration file if you add the prefix Eg.
|
If the "loginService" is set to "enovia", TIF will authenticate users against the ENOVIA database.
http.webapp.jaxrs.loginService=enovia
http.webapp.jaxrs.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
Secondly, an example for spnego:
http.webapp.jaxrs.loginService=spnego
http.webapp.jaxrs.spnego.targetName=HTTP/tifserver.exampledomain.com
http.webapp.jaxrs.realm=Webservices
Instead of specifying the targetName you may instead point out a property file that holds that value under the key targetName. See below: |
http.webapp.jaxrs.loginService=spnego
http.webapp.jaxrs.spnego.config=${tif.home}/etc/kerberos/spnego.properties
http.webapp.jaxrs.realm=Webservices
The spnego.properties
defines the targetName like this:
targetName = HTTP/tifserver.exampledomain.com
Within the "web.xml" file (webapps/jaxrs/WEB-INF/web.xml) you need to setup the rules for the application.
If you have not started TIF, you will not find the web.xml file, instead
it will be found under webapps/jaxrs/WEB-INF/web.xml.template . Upon start, TIF
will copy over the template file unless the web.xml file is found.
|
Below is an example when using ENOVIA/Basic authentication and how such might look like.
Note that in this example, each user that is supposed to use the web-services must have the role "WS-Integration-User". Note that depending on login service used (ldap or enovia), the role is either a LDAP role or a ENOVIA role.
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>WS-Integration-User</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
Below is an example for Spnego:
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>EXAMPLEDOMAIN.COM</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>SPNEGO</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
The access restriction can be defined based upon following:
Role Assignment
Group Assignment
Person (A named user)
Access Mask (Access mask for the current object)
Access Program (A JPO that evaluates the access rights)
Access Expression (MQL expression that evaluates the access)
The example below illustrates how you can construct the access restriction:
<Access>
<Role>role_FirstRole</Role>
<Role>role_SecondRole</Role>
<Group>group_SomeGroup</Group>
<Mask>modify,checkout</Mask>
</Access>
Or use an access program:
<Access>
<Program name="MyJPO" method="checkAccess"/>
</Access>
Or use an access expression:
<Access>
<Expression><![CDATA[owner == context.user]]></Expression>
</Access>
The expression will only be possible to utilize on service’s that operates on one (1) business object. If your service would use an ID locator that returns multiple objects, the expression has no affect. |
The IdLocator is responsible for locating the object the client is requesting. This is done by using the PathParameters and/or QueryParameters associated in the request. For example, the parameters includes type, name and revision of the object or interest.
There are a number of built-in strategies for locating the object. It is also possible to write a custom IdLocator.
IdLocators are optional. For example, a service returning all countries in the system does not require an IdLocator. |
Uses a dataset to locate the object/s. The PathParameters/QueryParameters and the requested mimetype is available when using parameterized datasets. More information about parameterized datasets is available in the TVC Core Admin Guide.
The first PathParameter is available with the key pathparam_0
, second one with
key pathpararm_1
and so on. The QueryParameters are available with the same
key as in the request to the service. The requested mime type uses the key mimetype
.
<Rest>
<ServiceName>product</ServiceName>
<IdLocator dataset="tvc:data/ProductInStateFinder.xml" />
...
</Rest>
<DataSet>
<LatestInState>
<State>$(pathparam_1,empty=false)</State>
<Query>
<NamePattern>
<Name>$(pathparam_0,empty=false)</Name>
</NamePattern>
<Limit>1</Limit>
</Query>
</LatestInState>
</DataSet>
tnr
3 (type/name/revision)
Uses type, name and revision to identify the object. A query is used in the background to find the matching object.
Name | Description | Default |
---|---|---|
AllowWildcards |
Defines if wildcards are allowed in the paramters. |
false |
Limit |
Maximum number of objects that can be found |
100 |
Where |
Where clause to use in query.
Example: |
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="tnr">
<Where>revision==last"</Where>
<Limit>1</Limit>
</IdLocator>
...
</Rest>
value
1 (value)
Identifies the object using a value on an attribute/basic. Uses a query in the background to find the matching object. For example, it can be a unique product number stored in an attribute.
Name | Description | Default |
---|---|---|
Limit |
Maximum number of objects that can be found |
100 |
Match |
Defines what attribute/basic to use to find the object of interest. This setting is mandatory. Example: |
|
Type |
Defines a type that object must be of. |
* |
Where |
Where clause to use in query. Example: |
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="value">
<Match>$<attribute[attribute_ProductId]></Match>
</IdLocator>
...
</Rest>
http://server-name:8181/enovia/jaxrs/service/product/9857847
objectid
1 (objectid)
Uses an object id to locate the object.
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="objectid" />
...
</Rest>
http://server-name:8181/enovia/jaxrs/service/product/1234.5678.9123.4567
Specify the qualified java class name in the attribute className
. The java class must implement the interface com.technia.tif.enovia.jaxrs.service.idlocator.IdLocator
.
/**
* Responsible for identifying objects requested by the client of a configurable
* REST web service.
*
* @since 2015.3.0
*/
public interface IdLocator {
/**
* Locates object id/s based on the provided input.
*
* @param ctx Information about this REST call
* @return The object id/s
* @throws IdLocatorException Thrown if problem occur. For example, if no
* object was found.
* @since 2015.3.0
*/
Collection<String> locateIds(ExecutionCtx ctx) throws IdLocatorException;
}
Implement the interface com.technia.common.xml.XMLReadable if your id locator support configuration settings.
|
The operation is the actual job to perform. For example, read information about an object.
The payload read operation extracts information from ENOVIA for the object/s. Note that object id/s only are available in case the REST service contains an IdLocator.
To read payload, configure attribute type
with value payload
.
In addition, specify a payload using the attribute payload
.
See page Payload Definition for details on how to define the payload definition.
<Rest>
...
<Read type="payload" payload="tvc:payload/Product.xml" />
</Rest>
The read operation supports generating content in XML or JSON format. The Accept
header is used to determine which format to use.
Accept Header Value | Description |
---|---|
application/xml |
Generates content in XML format. This is the default, if no format is specified. |
application/json |
Generates content in JSON format. |
To disable automatic payload transform based on the Accept
header, set attribute autoTransform
to false
.
<Rest>
...
<Read type="payload" payload="tvc:payload/Product.xml" autoTransform="false" />
</Rest>
It is also possible to define response content type explicitly in payload configuration. See Payload Definition. |
The file read operation can be used to extract files that are checked into an object. The extraction is done from one object per request. Therefore, exactly one object id is required. Object id is specified by an IdLocator.
To extract files, configure attribute type
with value file
. In addition, it can be configured with the following attributes which files should be included or excluded.
Attribute | Description |
---|---|
|
A comma separated list of file formats that should be used to include files. |
|
A comma separated list of file names that should be used to include files. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
A comma separated list of file names that should be used to exclude files. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Defines if the extraction result should be compressed into a ZIP file if the result contains only one file. If there are more than one file, the result will compressed into a ZIP file regardless of this setting. Use values "true" or "false". Default is "false", if not configured. |
|
Configures "Content-Disposition" header in the response. Valid values are Value Default is |
<Rest>
...
<Read type="file"
includeFormats="generic,zip"
includeFileNames="text*.txt,package*.zip"
excludeFileNames="*.doc"
zipOnlyFile="true"/>
</Rest>
Client may also add one or more request specific query parameters, that can be used to include or exclude files even more detailed per request. It should noticed that request specific filters cannot be used to extract files that configured filters do not allow. The following query parameters are supported.
Query Parameter | Description |
---|---|
|
File format that should be used. |
|
Name of file that should be included. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Name of file that should be exluded. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Can be used to override default content disposition configuration. See previous table for details. |
Client may also pass a list of filters by using multiple parameters.
http://server-name:8181/enovia/jaxrs/service/product/Sales+Item/1200-1000/A?includeFormat=generic&includeFileName=*123.txt&excludeFileName=*.zip
The file update operation can be used to check in files to an object. Check in can be done to one object per request. Therefore, exactly one object id is required. Object id is specified by an IdLocator.
A request should be done with method "PUT" and using multipart/form-data encoding.
To check in files, configure attribute type
with value file
.
<Rest>
...
<Update type="file"
format="generic"
existStrategy="newversion"
append="true"
useCDM="true"
unzip="false" />
</Rest>
In addition, it should be configured with the following attributes how files are checked in.
Attribute | Description | Required |
---|---|---|
|
Defines what should happen if a file with same name is already checked in. Use value "fail" if the operation should cause the request to fail. Use value "overwrite" if file should be overwritten. Use value "newversion" if new version of file should be created. In this case attribute "useCDM" must be "true". |
Yes |
|
Defines in which format file is checked in. |
Yes |
|
Defines if file should be appended to the object. If "false", then other files in same format are removed from object. Use value "true" or "false". If disabled, attribute "useCDM" or "unzip" cannot be "true". |
No, default is "true". |
|
Defines if Common Document Model or CDM is applied. Use value "true" or "false". If enabled, attribute "append" cannot be "false". |
No, default is "false". |
|
Defines if zipped uploaded files are extracted and their contents are checked in instead. Files are retrieved from the root level of ZIP package. Use value "true" or "false". If enabled, attribute "append" cannot be "false". |
No, default is "false". |
The create new job operation can be used to execute/run a new integration job. The request may be done context-less or in context of one or more objects; this all depends on how you have configured your REST job regarding IdLocator.
<Rest>
...
<NewJob jobcfg="TheJobCfgName.xml" />
</Rest>
When using this operation, you will see a minimum of two log entries in the Admin UI. One is for the actual REST job itself and the other is for the job(s) that you execute. |
A request should be done with the "POST" method. Example:
curl -X POST http://server:8181/enovia/jaxrs/service/new-job-from-rest/Part/EV-000001/A
The following attributes can be used on the <NewJob>
element
Attribute | Description | Required |
---|---|---|
|
Defines the Job configuration name to be used |
True |
|
This flag defines if the REST job should wait for the job to complete. Default is TRUE, e.g. do not wait for completion. Note that if your configuration resolves to multiple context objects, the job will be executed asyncronously anyway. |
No |
|
This flag can be used to specify that you want to return the generated payload from the job execution. Setting this to true, requires you to run the job synchronously.
E.g. the |
No |
HTTP status codes are used to communicate the status of the call to the client.
In case an error occurs a status code other than 200 is returned along with a description of the problem.
Code | Description |
---|---|
200 |
All ok |
400 |
One of the following:
|
415 |
Unsupported media type. The service is unable to produce content on the media type requested by the client. |
404 |
No object found. The provided PathParamters/QueryParamters didn’t match any object in ENOVIA. |
500 |
Unexpected error. View the response for details. |
501 |
Unsupported operation. The requested operation is not supported. |
TIF allows deploying RESTful Webservice’s.
You have to package your RESTful services in a JAR file together with a special file within the "META-INF/" folder of the JAR file that defines what packages TIF should scan for the annotated RESTful service classes.
The file inside the META-INF folder should have the name jax-rs-packages.properties
and this file should contain the package names (one per line in the file).
com.acme.integrations.erp.rest
com.acme.integrations.sap.rest
The JAR file should be dropped into the ${TIF_ROOT}/modules/enovia/webapps/jaxrs/WEB-INF/lib
directory. Upon startup of TIF, the REST services will be initialized.
Custom resource and provider classes can be registered by creating file jax-rs-classes.properties
into "META-INF/" folder. It should contain the class names one per line in the file.
com.acme.provider.MyProvider
com.acme.resource.MyResource
JAR file(s) containing registered classes must be dropped into the ${TIF_ROOT}/modules/enovia/webapps/jaxrs/WEB-INF/lib directory.
|
The default context URL to a RESTful service is shown below.
The port number may be different, see this page for details how to change it.
The context path to a web-application may be changed, see Module Settings for more info.
Use the example JAXRS bundled with TIF to test that everything is correctly setup. The current date will be returned in case all is okay.
Hosted RESTful web service is automatically logged in the TIF database. It appears as a REST service in Admin UI with display name that is a combination of invoked web service class and method name. The unique service name is constructed based on the values of Path annotation in both class and method. The service name is not visible in Admin UI, but it is used to identify the service.
For example:
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
@Path("/example")
public class MyExample {
@Path("/{param}")
@GET
public String success(@PathParam("param") String param) {
return param;
}
}
Considering the above example, the service display name would be "MyExample/success" and service name is "example/{param}".
There are configurable webapp init parameters to set maximum length for logged inbound (request) and outbound (response) payloads. Parameters help to limit usage of heap memory and storage by preventing to persist too large payloads to TIF DB.
See parameters "inboundPayloadMaxLength" and "outboundPayloadMaxLength" in web.xml
.
Default value for parameters is 1 000 000 bytes, if not defined. |
There is a Apache CXF base webapp under ${TIF_ROOT}/modules/enovia/webapps/cxf
that can be used as base/template for CXF based web services.
There are own servlet filters for SOAP and RESTFul web services that can be used for logging web service calls to TIF DB. See web.xml
for filter details. Also, there is cxf-servlet.xml
that contains configurations for example web services.
If you have not started TIF, you will not find the web.xml or cxf-template.xml file, instead there are template files. Upon start, TIF will copy over the template file unless the web.xml or cxf-template.xml file is found. |
When using the CXF logger filter for RESTful web services, the web service call is logged in the TIF database. It appears as a REST service in Admin UI with display name that is a combination of invoked web service class and method name. The unique service name is constructed based on the values of Path annotation in both class and method. The service name is not visible in Admin UI, but it is used to identify the service.
For example:
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
@Path("/example")
public class MyExample {
@Path("/{param}")
@GET
public String success(@PathParam("param") String param) {
return param;
}
}
Considering the above example, the service display name would be "MyExample/success" and service name is "example/{param}".
When using the CXF logger filter for SOAP web services, the web service call is logged in the TIF database. It appears as a SOAP service in Admin UI.
See the filter settings in ${TIF_ROOT}/modules/enovia/webapps/cxf/web.xml
for details how the service name (visible in Admin UI) is constructed.
There are configurable webapp init parameters to set maximum length for logged inbound (request) and outbound (response) payloads. Parameters help to limit usage of heap memory and storage by preventing to persist too large payloads to TIF DB.
See parameters "inboundPayloadMaxLength" and "outboundPayloadMaxLength" in web.xml
.
Default value for parameters is 1 000 000 bytes, if not defined. |
A reply handler is responsible for handling asynchronous replies from other systems and update the status of the job (which is the source for the reply) inside TIF. This is a crucial mechanism if you are interested in receiving events upon completion or failure of a integration job.
A typical use case is when you transfer data to a messaging queue and you expect a reply from the "other" system onto a reply-queue, then you need some functionality that consumes messages from the reply-queue in order to update the job status in TIF; e.g. mark the job as succeeded or failed.
Currently, you may handle replies using a configurable reply handler from following sources:
Support for receiving events from the OS when a file is changed/added in a directory may be used to communicate reply status.
Consume messages from a particular JMS queue used for replies
Consume messages from an IBM MQ queue used for replies
Consume messages from a Rabbit MQ queue
A reply handler will take care about most of the details regarding receiving the reply and perform the internal calls inside TIF but provide extension points were necessary. For example, allow evaluating if the reply represents a positive or negative response.
A reply handler works like this
Get/obtain message from some source
From the message and its source - map to the originating Job / Transfer
This is typically done either via correlation id or through some custom evaluation
Based upon the content of the message, evaluate if the response is successful or failing
This is the place were you will need to plugin some code that does this evaluation.
Update the TIF internally
A reply handler is defined in an XML resource within the ${TIF_ROOT}/modules/enovia/cfg
directory of type "replyhandler".
Example:
${TIF_ROOT}/modules/enovia/cfg/replyhandler/MyReplyHandler.xml
${TIF_ROOT}/modules/enovia/cfg/domain/replyhandler/MyReplyHandler.xml
these configuration files are referenced as
tvc:replyhandler/MyReplyHandler.xml
tvc:replyhandler:domain/MyReplyHandler.xml
A configuration defines the following aspects:
The source
How the mapping between message and Job id is made
How to evaluate the status
If you need an ENOVIA™ context available during the execution. (default none is allocated)
Lets look at the configuration format. Note that this is not a valid example it just illustrates all configuration aspects.
<ReplyHandler>
<Source>
<JMS id="eco-reply" /> (1)
<NativeMQ id="mq-eco-reply" />
<RabbitMQ id="rabbitmq-eco-reply" />
<File id="file-in-1" replyFor="file-out-1"/>
</Source>
<JobIdLocator className="com.acme.custom.MyJobLocator" /> (2)
<JobIdLocator script="MyIDLocator.js" />
<JobIdLocator script="tvc:script/MyIDLocator.js" />
<JobIdLocator script="tvc:script:domain/AnotherIDLocator.js" />
<JobIdLocator>
importClass(com.technia.tif.enovia.job.reply.config.JobIDLocator.ID);
function locate(msg) {
...
return new ID(UUID.fromString(jobId), transferId);
}
</JobIdLocator>
<StatusEvaluator className="com.acme.custom.MyStatusEvaluator" /> (3)
<StatusEvaluator script="MyStatusEvaluator.js" />
<StatusEvaluator script="tvc:script/MyStatusEvaluator.js" />
<StatusEvaluator script="tvc:script:domain/AnotherStatusEvaluator.js" />
<StatusEvaluator>
function evaluate(ctx) {
ctx.setResult(true, "OK");
}
</StatusEvaluator>
<WithContext /> (4)
</ReplyHandler>
1 | Either one of these sources can be used per reply handler |
2 | The JobID locator |
3 | The StatusEvaluator |
4 | Optionally element that, if present, will allocate a context for you. |
The <WithContext>
element supports the following attributes.
Attribute | Required | Description |
---|---|---|
user |
No |
If omitted, the super user will be used |
securityContext |
No |
Defines the security context to be used |
useDefaultSecurityContext |
No |
If set to true, the default security context for the user will be used. The used user must have a default security context otherwise an error will be raised. |
Both the job-id locator and status-evaluator may be implemented in a few different ways:
A Java class implementing either com.technia.tif.enovia.job.reply.config.JobIDLocator
for JobIdLocator and com.technia.tif.enovia.job.reply.config.StatusEvaluator
for StatusEvaluator.
A script stored inside its own file using the script resource type.
An inline script.
In some cases you may not need a JobID locator. See next chapter(s). |
If you are using Java 8, the internal Java Script engine has been changed so you may need to change your old legacy scripts by adding the following at the top of your script:
|
The supported attributes on the JMS element are shown in the table below
Attribute | Description | Required |
---|---|---|
id |
The id of the corresponding destination |
Yes |
messageSelector |
A message selector that filters messages. See below for details |
No |
transacted |
Boolean defining transaction mode |
No. Default is false |
ackMode |
One of "auto","client" or "dups_ok" |
No. Default is auto |
consumerCount |
Defines number of concurrent consumers. Typically used with destination listening to a queue. |
No. Default is 1 |
shareConnection |
Boolean defining if to share connection per destination with other JMS listeners. The common default value can be configured with property |
No |
For handling of replies from a JMS messaging systems the correlation id is used to correlate the message to its "source" in TIF.
If you have changed the format of the correlation id in the outgoing message, you need to apply changes in the reply handler. |
By default, the message selector that is used for a JMS Source is set to
JMSCorrelationID like '${tif.instance.id}|%'
The macro is resolved at runtime to the id of the TIF instance.
This means that only messages matching this correlation id will be fetched from the TIF instance in question. This is particularly useful in situations where you have multiple TIF instances listening to the same queues. In such case it is important that only the TIF instance that sent the original message will receive the reply.
If you are using the default correlation id on the outgoing JMS message, you do not need to define a JobIdLocator
at all since the mapping can be done automatically.
Example config for JMS source were response message is of type TextMessage and the status is provided as a property on the message object.
<ReplyHandler>
<Source>
<JMS id="eco-reply" />
</Source>
<StatusEvaluator>
function evaluate(ctx) {
var msg = ctx.getMessage().getText();
var succeeded = ctx.getMessge().getBooleanProperty("success");
ctx.setResult(succeeded, msg);
}
</StatusEvaluator>
</ReplyHandler>
The supported attributes on the RabbitMQ
element are shown in the table below
Attribute | Description | Required |
---|---|---|
id |
The id of the corresponding destination |
Yes |
Replies from a Rabbit MQ messaging system uses the correlation id of the message to correlate the message to its "source" in TIF.
If you have changed the format of the correlation id in the outgoing message, you need to apply changes in the reply handler. |
By default, outgoing messages from TIF to RabbitMQ uses a correlation id that contains the following information
TIF instance id
Job id
Transfer id
The TIF instance id is needed in order to be able to correlate messages to the correct TIF instance. E.g ensure that the same TIF instance that sent the original message will handle the reply.
If you are using the default correlation id on the outgoing Rabbit MQ message,
you do not need to define a JobIdLocator
at all since the mapping can be done automatically.
Example config.
<ReplyHandler>
<Source>
<RabbitMQ id="eco-reply" />
</Source>
<StatusEvaluator>
function evaluate(ctx) {
var msg = ctx.getMessage().getBodyAsString();
var succeeded = ctx.getProperties().getHeaders().get("status");
ctx.setResult(succeeded, msg);
}
</StatusEvaluator>
</ReplyHandler>
The supported attributes on the NativeMQ element are shown in the table below
Attribute | Description | Required |
---|---|---|
id |
The id of the corresponding destination |
Yes |
defaultMatchGroupId |
Whether or not if to match on group id’s. Note that per default this attribute is based upon the TIF setting See also this chapter. By default TIF will match messages based upon their group-id’s. |
No |
messageId |
Used to specify match option on the message-id |
No |
correlationId |
Used to specify match option on the correlation-id |
No |
groupId |
Used to specify match option on the group-id |
No |
seqNumber |
Used to specify match option on the sequence number |
No |
For handling of replies from a JMS messaging systems the correlation id is used to correlate the message to its "source" in TIF.
If you have changed the format of the correlation id in the outgoing message, you need to apply changes in the reply handler. |
Example config for Native MQ source.
<ReplyHandler>
<Source>
<NativeMQ id="MQ.QM1.M3.REPLY" />
</Source>
<StatusEvaluator>
function evaluate(ctx) {
....
ctx.setResult(succeeded, msg);
}
</StatusEvaluator>
</ReplyHandler>
Some use cases involves creating files in folders that are watched by other applications. In order to receive status updates from such operation, you can use a File source to listen into a folder, which the other system is responding into.
<ReplyHandler>
<Source>
<File id="file-dest-2"
replyFor="file-dest-1"/>
</Source>
<StatusEvaluator className="com.technia.tif.enovia.job.reply.config.SimpleFileStatusEvaluator" />
</ReplyHandler>
In this example we use the default ID locator, which assumes that the file name is the "job id" + an optional suffix.
In the destinations.xml
file you may define the outgoing file destination like below in order to include the job-id in the outgoing file-name.
<Destinations>
<File id="file-dest-1"
directory="${tif.temp}/transfer/out"
fileName="${job.id}.xml"/>
<File id="file-dest-2"
directory="${tif.temp}/transfer/in"/>
Moreover, we use a built-in status evaluator that has a very simple implementation:
public void evaluate(ReplyHandlerContext ctx) {
Path p = ctx.getMessage();
String dirName = p.getParent().getFileName().toString();
boolean error = "error".equalsIgnoreCase(dirName);
ctx.setResult(!error, readFileContent(p));
}
Upon startup, TIF will automatically find all reply handler configurations that you have configured and deploy these. This method is called auto-registration and can be disabled if wanted. Below is a table of properties that are of interest.
Property | Type | Default | Description |
---|---|---|---|
resources.replyHandler.autoRegister |
boolean |
True |
Use this property to disable the auto registration |
resources.replyHandler.excluded |
Comma separated list |
Comma separated list of resources to be excluded. |
|
resources.replyHandler.included |
Comma separated list |
Comma separated list of resources to be included. |
By default, auto registration is enabled and no resources are excluded.
In earlier versions of TIF, you were forced to specify the reply handler configurations
to be started within the ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
file.
This method is still supported, although the preferred approach is to auto-register
all configurations without having to also do extra configuration within the "module.custom.properties" file.
To deploy a reply handler using the old approach, see instructions below:
replyHandler.<id>.<property> = <value>
Below is an example where two different reply handlers has been configured.
replyHandler.0.config = ECOReply.xml
replyHandler.1.config = tvc:replyhandler:domain/PartReply.xml
Refering to configurations in the default domain do not require the complete expanded name. E.g. |
Each reply handler may be stopped / restarted from the TIF Administration UI. |
The most common configurations requires only the "config" property to be defined. However, there are additional properties available as shown below:
replyHandler.<id>.enabled = true (1)
replyHandler.<id>.config = ... (2)
replyHandler.<id>.className = ... (3)
1 | May be used to disable a particular reply handler |
2 | Specifies the reply handler configuration |
3 | Instead of a configuration, specify a Java class implementing com.technia.tif.enovia.job.reply.ReplyHandler |
The earlier supported properties called
Are no longer supported. You should configure this from within the reply handler instead using the |
The create and/or update integration allows you to setup use cases, which will enable support for
Create or Update a single object
Create or Update multiple objects
Create or Update objects and relationships connected in a single or multi level fashion
The integration does not require a certain format of the incoming payload (the incoming data), instead it is via the create/update configuration you specify how the data is formatted and what actions that should be taken.
The create/update configuration is defined in an XML file, which should be stored
within a folder called "createconfig" below ${TIF_ROOT}/modules/enovia/cfg
.
You need to have some basic knowledge in XPath expressions, in order to understand how to write your configurations to match/map to the incoming payload data. |
The create/update configuration can operate in two different modes depending on the use case, e.g. contextual and non-contextual. Contextual means that the integration runs in the context of a certain business-object, while in the other case it is the incoming payload that contains all information.
The create/update configuration contains on a high level:
Format of incoming data
Instructions from where in the incoming data to start the processing.
This is done via <EntryPoint>
definitions.
Rules depending on what data that has been matched. This is done via
<Config>
definitions.
The root element within a create/update configuration is <CreateConfiguration>
,
and this element supports the following attributes:
Attribute | Description | Type | Default |
---|---|---|---|
requiresInputObject |
Whether or not to run the integration in contextual mode or not. |
Boolean |
False |
runPrivileged |
Can be used to enforce running the integration as a super-user. This may be useful in situations where the current user do not have sufficient privileges to perform certain changes in the database. |
Booolean |
False |
historyOff |
May be used to turn off history logging while running the integration. |
Booolean |
False |
triggerOff |
May be used to turn off triggers while running the integration. |
Booolean |
False |
maxLevels |
May be used to restrict the integration to process structures deeper than this value. No restrictions are defined by default. |
Integer |
-1 |
txType |
The transaction type to be used while running the integration. Possible values are
|
String |
update |
dateFormat |
The default date format to be used when parsing date values from the incoming data. The value should either be a valid date pattern string, or one of the following pre-defined values:
|
String |
iso-date-time |
xpathFactory |
Define a custom XPathFactory to be used.
Either you point out a class using its fully qualified name, or use the short names
|
String |
Default is |
listener |
Name of class implementing
May be used to listen to event’s occurring during the integration execution |
String |
The allowed child elements are:
Child Element | Cardinality | Required | Description |
---|---|---|---|
|
0 or 1 |
No |
May be used to handle more complex input formats, for example ZIP input |
|
1+ |
Yes |
Defines entry points, e.g. where to look for the starting point within the incoming payload. |
|
1+ |
Yes |
Defines the create/update rules for a given kind of element. |
|
0+ |
No |
May be used to define different kind of translations of incoming values to ENOVIA™ understandable values. |
|
0 or 1 |
No |
May be used to point out an XML Schema to be used for validation of the incoming payload. |
|
0 or 1 |
No |
Configure the namespace context while evaluating XPath expressions during the processing. |
With the <InputFormats>
element you can specify what kind of format the incoming
data should have. By default, if this is not specified, the incoming data is
assumed to be an XML file processed as-is.
If you omit the <InputFormats> element, we assume that the data passed
in to the create/update integration is XML data.
|
The following input formats are supported:
XML, which is handled as-is without any conversion
XML that is converted to another XML format using an XSLT stylesheet.
JSON data that is converted automatically to XML
Comma separated values. Automatically converted to XML.
ZIP file containing the data
Allowed child elements are:
Child Element | Supported Attributes | Description |
---|---|---|
|
- |
Used to process ZIP input files. ZIP files may contain both meta-data and additional files, which for example may be checked-in to objects being created and/or updated during the process. |
|
|
Used for conversion of CSV data into XML for further processing |
|
|
Used for converting XML data into another XML format for further processing |
|
|
Used for converting JSON data into XML. |
|
- |
E.g. just use the default input, assumed to be XML without need for further conversion. |
A ZIP file contains multiple files, and you need to specify what files within the ZIP archive that contains the data that should be processed by the create / update integration engine. You can either point out a single file by its path/name or use globbing pattern to match multiple files.
<InputFormats>
<Zip>
<InputFiles>data.xml</InputFiles>
</Zip>
</InputFormats>
Note that if the data you are processing is in a different format, you need to transform it to XML. Supported transformers are CSV, XML and JSON.
<InputFormats>
<Zip>
<InputFiles>data/*.csv</InputFiles>
<Transformer> (1)
<CSV charset="UTF-8" separator="," includesHeader="true" />
</Transformer>
</Zip>
</InputFormats>
1 | For CSV data, we need to transform it to XML. |
JSON data is converted to XML as shown in the examples below:
JSON | XML |
---|---|
|
|
|
|
1 | Any occcurence of invalid XML name character is removed when transforming a JSON property name into an XML element name. E.g. the space is being removed. |
2 | In this case, the whole name was invalid - hence we use the fallback element name. |
CSV is fairly easy to transform into XML. Each row in the CSV data is mapped to a
<row>
element and each field is contained in a <field>
element.
See below for an example how the CSV data is converted to XML
Part,A-0001,B,Release,45 g
Part,A-0002,C,Release,94 g
<data>
<row>
<field>Part</field>
<field>A-0001</field>
<field>B</field>
<field>Release</field>
<field>45 g</field>
</row>
<row>
<field>Part</field>
<field>A-0002</field>
<field>C</field>
<field>Release</field>
<field>94 g</field>
</row>
</data>
Depending on if you run in contextual mode or not (by using the requiresInputObject attribute), you need to use the EntryPoint element in two different ways.
Lets start with the non-contextual mode, in this mode you only need to specify the select attribute and optionally the mode attribute. The select attribute specifies an XPath expression, which will select an element or a list of elements from the incoming payload. Below are some examples
<EntryPoint /> (1)
<EntryPoint select="/" /> (2)
<EntryPoint select="/Data/Items/Item" /> (3)
1 | Implicitly selects the first level elements below the root element of the incoming payload. |
2 | Selects the root element of the incoming payload |
3 | Selects the elements (or element) matching the given XPath |
The optional mode attribute may be used to process the matched elements in a particular mode. We will discuss the mode attribute more further in the document.
Example:
<EntryPoint select="/Data/Items/Item" mode="root" />
Alternative 2, when processing in contextual mode: In this case, you will not use the select nor the mode attributes. Instead, you will use one or more child elements below the EntryPoint element called ContextObject, which defines for what context object it is valid for and how the context object is connected to the incoming payload. Example:
<EntryPoint>
<ContextObject match="type.kindOf[Part] AND current == 'Release'"> (1)
<Connections>
<Connection relationship="relationship_EBOM" select="/Data/BOM/rows" /> (2)
</Connections>
</ContextObject>
<ContextObject match="type.kindOf[Product]'"> (3)
...
</ContextObject>
<ContextObject> (4)
...
</ContextObject>
...
</EntryPoint>
1 | Configuration used when context object matches the ENOVIA expression, e.g. for released Part’s. |
2 | Connection configuration (See later section for more details). Specifies for different kind of relationship(s) how to connect the context object with the incoming data. The select attribute defines an XPath expression that maps to data that represents objects that should be connected with this relationship. NOTE: You may have multiple Connection elements. |
3 | Configuration used when context object is of type Product. |
4 | Fallback configuration, which matches any context object. |
The match attribute must be a valid ENOVIA™ expression, which is evaluated against the database by TIF. You can test your expressions via MQL by using the following syntax.
|
If you omit the match attribute, it implies that it will be valid for any kind of object.
However, the order a <ContextObject>
definition is being resolved, is that the first one that matches will be used.
If none matched, but there is a configuration with an empty (or missing) match attribute,
that configuration will be used.
The Config element describes what to actually do with the incoming data. A single Config definition is mapped to operate against a certain element (or elements) from the incoming payload.
This matching is done via the name of the current element that has been selected either via the EntryPoint or via a Connection
Below are some examples of such mapping.
E.g. the select attribute on either the <EntryPoint>
or <Connection>
elements
consists of an XPath expression that is evaluated from the current position of the
incoming payload. The matched elements are then mapped to a certain <Config>
element,
which contains instructions on how to handle the data.
The mode attribute may be used to allow processing of an element using different configurations, depending on the current processing mode. |
The allowed attributes on the <Config>
element are:
Attribute | Description | Type | Default |
---|---|---|---|
match |
Defines the name of the XML element from the incoming payload, which this config is valid for. |
String |
|
mode |
An optional value that defines the mode, which this config is valid for |
String |
The allowed child elements are:
Child Element | Cardinality | Required | Description |
---|---|---|---|
|
0 or 1 |
No |
Defines what to do, if the object the current element in the incoming payload represents exists in the ENOVIA™ database. Possible values are:
|
|
0 or 1 |
No |
Defines behavior when the current element in the incoming payload does not map to an object inside the ENOVIA™ database. Possible values are:
|
|
1 |
Yes |
Defines how to find the object inside the ENOVIA™ database based upon the incoming values. |
|
0 or 1 |
No |
Defines how to create the object inside the ENOVIA™ database based upon the incoming values. |
|
0 or 1 |
No |
Defines how to update the object inside the ENOVIA™ database based upon the incoming values. |
|
0 or 1 |
No |
Specifies optional connections that should be created or updated. |
|
0 or 1 |
No |
May be used to configure how to deal with file content that has been embedded within the incoming data. |
The logic follows this flow:
The rules inside the <IdentityMatch>
defines how to obtain values required
for identifying the object inside the ENOVIA™ database.
If no object could be mapped AND the <CreateValues>
section has been defined,
TIF will try to create the object based upon the values given. Note that in the
case for create, values defined within the <IdentityMatch>
but not in the
<CreateValues>
section will be part of the create operation.
If ONE object were found, TIF will if BOTH <IfFound>
is set to update and
the <UpdateValues>
has been defined, try to update the object inside the database.
If more than one object were found, an exception will be raised and the processing will abort.
If <IfNotFound>
is set to revise, special revisioning rules are applied. See this chapter for more details.
The purpose of the <IdentityMatch>
element is to define values used to identify
the object in ENOVIA.
The child elements are used to identify data that maps to certain fields inside ENOVIA. You may combine the elements as needed/required depending on the use-case.
Note that there are some common attributes shared by all child elements (except the CustomField).
String, defines an XPath expression that is used to select the value from the incoming payload data.
String, May be used to declare a custom return type from the select expression. Particular if you are using xpath functions, this needs to be defined. Allowed values are: NODE, NODESET, STRING, NUMBER and BOOLEAN.
String, defines a fallback value to be used. May be used if you don’t expect the value to be present within the incoming payload data.
String, defines an optional value-mapper definition, which is used to lookup the value against.
Boolean, default is true for Type, Policy and Vault values. Defines if to treat value as a symbolic name, e.g. is to resolve it.
Boolean, default is false except for attribute fields and the description field. Defines if to allow empty values.
The table below shows the possible child elements and its additional attributes that may be of interest to use in the context of identity matching.
Child Element | Valid Attributes in context of Identity Match | Notes |
---|---|---|
|
|
|
|
|
|
|
Note: The attribute latest and last are used in conjunction to each other. If no revision in the given state was found, you can fallback to last revision. If this behavior is unwanted, set the last attribute to false. |
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
- |
|
|
- |
|
|
- |
|
|
|
|
|
- |
No other fields are allowed in identity match. |
|
- |
No other fields are allowed in identity match. |
|
Up to implementation |
Below follows some examples how to construct an Identify Matching.
Example 1:
<Config match="Part">
<IdentityMatch>
<Type fallbackValue="Part"/>
<Name select="@n" />
<Revision select="@rev" />
</IdentityMatch>
</Config>
This would work on data that is structured like this
<Part n="A-000101221" rev="C">
...
</Part>
Example 2:
<Config match="Part">
<IdentityMatch>
<Type select="Type/text()"/>
<Name select="Name/text()" />
<Revision latest="true" select="State/text()" />
</IdentityMatch>
</Config>
This would work on data that is structured like this
<Part>
<Type>Hardware Part</Type>
<Name>A-000101221</Name>
<State>Release</State>
...
</Part>
Example 3:
<Config match="Something">
<IdentityMatch>
<Attribute name="attribute_UUID" select="@uuid" />
</IdentityMatch>
</Config>
This would work on data that is structured like this
<Something uuid="8a9616bc-ae81-4532-87f3-214993789016">
...
</Something>
The purpose of the <CreateValues>
element is to define values used when creating
objects inside the ENOVIA™ database.
The child elements are used to identify data that maps to certain fields inside ENOVIA. You may combine the elements as needed/required depending on the use-case.
Fields defined within the <IdentityMatch> section will automatically be part
of the <CreateValues> unless they are overridden in the <CreateValues> section.
|
Note that there are some common attributes shared by all child elements (except the CustomField).
String, defines an XPath expression that is used to select the value from the incoming payload data.
String, May be used to declare a custom return type from the select expression. Particular if you are using xpath functions, this needs to be defined. Allowed values are: NODE, NODESET, STRING, NUMBER and BOOLEAN.
String, defines a fallback value to be used. May be used if you don’t expect the value to be present within the incoming payload data.
String, defines an optional value-mapper definition, which is used to lookup the value against.
Boolean, default is true for Type, Policy and Vault values. Defines if to treat value as a symbolic name, e.g. is to resolve it.
Boolean, default is false except for attribute fields and the description field. Defines if to allow empty values.
Child Element | Valid Attributes in context of Create |
---|---|
|
- |
|
|
|
|
|
|
|
- |
|
- |
|
|
|
- |
|
- |
|
- |
|
|
|
|
|
|
|
|
|
Up to implementation |
Below are some examples how to construct a create value section.
Example 1:
<Config match="Part">
<IdentityMatch> (1)
<Type select="@t" valueMapper="type-mapping" />
<Name select="@n" />
<Revision latest="true" fallbackValue="Release" />
</IdentityMatch>
<CreateValues> (2)
<Revision firstInSequence="true" />
<State fallbackValue="Release" />
<Policy fallbackValue="policy_ECPart" />
<Owner fallbackValue="tiftest" />
<Originated select="@created" dateFormat="iso-date" />
<Vault fallbackValue="vault_eServiceProduction" />
</CreateValues>
</Config>
1 | Values set here but not in the <CreateValues> section are also part of
the create operation. In this case, the Revision field is the only overridden field. |
2 | Defines the necessary values to create the object. In this example static/fallback values are used heavily. |
The purpose of the <UpdateValues>
element is to define values used when updating
objects inside the ENOVIA™ database.
The child elements are used to identify data that maps to certain fields inside ENOVIA. You may combine the elements as needed/required depending on the use-case.
Note that there are some common attributes shared by all child elements (except the CustomField).
String, defines an XPath expression that is used to select the value from the incoming payload data.
String, May be used to declare a custom return type from the select expression. Particular if you are using xpath functions, this needs to be defined. Allowed values are: NODE, NODESET, STRING, NUMBER and BOOLEAN.
String, defines a fallback value to be used. May be used if you don’t expect the value to be present within the incoming payload data.
String, defines an optional value-mapper definition, which is used to lookup the value against.
Boolean, default is true for Type, Policy and Vault values. Defines if to treat value as a symbolic name, e.g. is to resolve it.
Boolean, default is false except for attribute fields and the description field. Defines if to allow empty values.
Child Element | Valid Attributes in context of Create |
---|---|
|
- |
|
- |
|
|
|
- |
|
- |
|
- |
|
|
|
|
|
|
|
|
|
Up to implementation |
Below are some examples how to construct an update value section.
Example 1:
<Config match="Part">
....
<UpdateValues>
<Attribute name="attribute_Weight" select="@weight" />
<Attribute name="attribute_UnitOfMeasure" select="@uom" />
<Attribute name="attribute_SparePart" select="@sparePart" />
<Modified select="@modified" dateFormat="iso" />
</UpdateValues>
</Config>
If you don’t want to set the same values during create as in the update case,
set the attribute useForCreate="false" on the <UpdateValues> element.
|
As seen in previous chapters related to the elements <IdentityMatch>
, <CreateValues>
and <UpdateValues>
, an element called <CustomField>
has been mentioned.
This field may be used to handle more complex data. To use it, you use the following syntax:
<CustomField className="com.acme.SomeClass" />
This class must implement the interface com.technia.tif.enovia.integration.create.def.Field
.
You may use the create/update integration to create and/or update connections within the ENOVIA™ database.
The <Connections>
element is valid to use either within a <Config>
section or
within the <EntryPoint>
section in case you run the integration within a context object.
The <Connections>
element is just a place holder for one or more <Connection>
elements.
The <Connection>
element supports the following attributes
Attribute | Required | Description | Type | Default |
---|---|---|---|---|
select |
Yes |
Defines an XPath expression that is used to select the "children" from the incoming payload |
String |
|
mode |
No |
Defines what mode to process the child nodes within (This relates to what |
String |
|
relationship |
Yes |
Defines the name of the ENOVIA relationship to be used (symbolic names are allowed) |
String |
|
direction |
No |
Default is FROM, may be used to switch direction to TO |
from or to |
from |
typePattern |
No |
Optional type pattern (comma separated list of type names) to be used when expanding data in ENOVIA and matching with incoming payload |
String |
|
objectWhere |
No |
Optional where clause to apply on objects used when expanding data in ENOVIA and matching with incoming payload |
String |
|
relationshipWhere |
No |
Optional where clause to apply on relationships used when expanding the data in ENOVIA and matching within incoming payload |
String |
|
disconnectExisting |
No |
A flag to indicate whether or not to disconnect existing relationships, that NOT is mapped to the incoming payload |
Boolean |
False |
oneToOne |
No |
A special attribute that can be used to indicated that the connection will always either have none or one object connected |
Boolean |
False |
The allowed child elements are:
Child Element | Cardinality | Required | Description |
---|---|---|---|
|
0 or 1 |
Yes, unless the special attribute oneToOne has been set to true |
Defines how to map the incoming data into a particular relationship inside ENOVIA. See below how to construct an identity matching for relationships |
|
0 or 1 |
No |
Defines how to create the relationship inside the ENOVIA™ database based upon the incoming values. |
|
0 or 1 |
No |
Defines how to update the relationship inside the ENOVIA™ database based upon the incoming values. |
The identity matching for relationships are constructed by defining a combination of values, where each value either is related to the object or from the relationship itself.
Example 1:
<Connection ...>
<IdentityMatch>
<Relationship>
<Attribute name="attribute_FindNumber" select="@findNumber" />
</Relationship>
<Object>
<Name select="@identifier" />
</Object>
</IdentityMatch>
</Connection>
This would construct an identity matcher, which will map the attribute findNumber from the incoming data to the "Find Number" attribute-value of the relationship in the database combined with the name on the related object mapped to the attribute identifier.
You may use either or both values from the relationship or the related object, in order to conduct the identity matching.
Allowed children of the <IdentityMatch>
/<Relationship>
element:
Child Element | Description |
---|---|
|
Maps to the relationship type |
|
Attribute from the relationship |
|
Ownership |
|
Ownership (altowner1) |
|
Ownership (altowner2) |
|
Modified date |
|
Originated date |
|
Custom field mapping |
Allowed children of the <IdentityMatch>
/<Object>
element:
Child Element | Description |
---|---|
|
Maps to object type |
|
Maps to object name |
|
Maps to object revision |
|
Maps to object policy |
|
Maps to object vault |
|
Maps to object state |
|
Maps to object description |
|
Maps to object owner |
|
Maps to object alt-owner1 |
|
Maps to object alt-owner2 |
|
Maps to object modified |
|
Maps to object originated |
|
Maps to object attribute |
|
Custom field mapping |
For the child elements <CreateValues>
and <UpdateValues>
, see previous chapters.
With the <EmbeddedFiles>
element you can deal with files that is part of the payload.
The files may either be part of the payload itself, e.g embedded in the XML data,
or part of the ZIP file being used for processing the create/update use-case.
Three modes exists:
Files embedded directly in the payload, typically base-64 encoded file content
Files part of the ZIP file, and the payload refernces or uses files from it
Files part of the ZIP file, but no direct reference to the files from the payload, instead the files are mapped using a file-mapper.
It is not recommended to embed too many files within the incoming payload for performance reasons, choose instead to use a ZIP file when the amount of files are large or the size of the files are large.
The <EmbeddedFiles>
element is just a container for one or more <File>
elements.
The <File>
elements supports these common attributes:
Attribute | Description | Type | Default |
---|---|---|---|
select |
Defines an XPath expression, used to obtain the element(s) representing the file content. |
String |
. |
cdm |
Defines if to use CDM mode or not. Default is to autodetect this. Possible values are:
|
String |
auto |
reuseVersion |
In case of CDM mode, this attribute can be used to enforce creation of new version |
Boolean |
False |
appendFile |
If to append the file |
Boolean |
True |
unlock |
If to unlock object |
Boolean |
True |
multiple |
May be used to specify if multiple files are expected from the incoming payload |
Boolean |
True |
nameSelect |
An XPath expression to be used to select the name of the file from the current element |
String |
|
nameSelectReturnType |
Allowed values are: NODE, NODESET, STRING, NUMBER and BOOLEAN. |
String |
NODE |
nameFallback |
A static value for the file-name, may only be used IF the multiple attribute has been set to FALSE |
String |
|
formatSelect |
An XPath expression used to select the format of the file |
String |
|
formatSelectReturnType |
Allowed values are: NODE, NODESET, STRING, NUMBER and BOOLEAN. |
String |
NODE |
formatFallback |
A static value for the format to be used |
String |
To use embedded files mode, one need some additional attributes
Attribute | Description | Type | Default |
---|---|---|---|
contentSelect |
An XPath expression used to select the content of the file |
String |
|
contentEncoding |
The encoding used when converting the encoded string into bytes |
String |
UTF-8 |
encoding |
Specifies in what encoding format the content is encoded in. Currently only base64 is allowed/supported |
String |
base64 |
Lets look into an example how this could be utilized.
Example of incoming data, which would map to an objects image holder (note that the content has been cropped to reduce space). File content is embedded within the source XML data.
<Data>
<Items>
<Item id="fa-fe-2c-2d" t="Part" n="XZ-0001" rev="A" w="100 g">
...
</Item>
</Items>
<Images>
<Image ref="fa-fe-2c-2d">
<Content format="mxImage" name="image.png">iVBORw0KGgoAAAANSUhEUgAAAQoAAAFmCAMAAACiIyTaAAABv1BMVEU...
<Config match="Item">
...
<Connections>
<Connection
oneToOne="true"
relationship="relationship_ImageHolder"
direction="to"
select="/Data/Images/Image[@ref = current()/@id]" (1)
mode="Image Holder" />
<Config match="Image" mode="Image Holder"> (2)
<CreateValues>
<Type fallbackValue="type_ImageHolder" />
<Name useSystemTime="true" prefix="auto_"/>
<Revision fallbackValue="" />
<Policy useFirst="true" />
<Vault fallbackValue="vault_eServiceProduction" />
</CreateValues>
<EmbeddedFiles>
<File (3)
cdm="false"
multiple="true"
append="true"
encoding="base64"
select="Content"
nameSelect="@name"
formatSelect="@format"
formatFallback="generic"
contentSelect="text()" />
</EmbeddedFiles>
</Config>
1 | Connection defined for Item, used to create the image holder |
2 | Configuration for creation / updating of the Image Holder |
3 | File element that instructs how to find the files to be checked in. |
To use the file reference mode, one need some additional attributes
Attribute | Description | Type | Default |
---|---|---|---|
fileRefSelect |
Depends on input format. For example if you use ZIP input format, your data may refer to a file within the ZIP archive and this attribute specifies the XPath expression that would select the file reference name. The name is then used when querying the Content Handler for the used Input Format. |
String |
|
fileRefPrefix |
Can be used to prepend some path prefix to the selected value |
String |
|
fileRefSuffix |
Can be used to append some path suffix to the selected value |
String |
Example:
<Data>
<Images>
<Image name="..." rev="...">
<File fileName="image1.png" format="Large"/>
<File fileName="image2.png" format="Medium"/>
<Config match="Image">
...
<EmbeddedFiles>
<File
cdm="false"
multiple="true"
append="true"
fileRefSelect="File"
fileRefPrefix="files/"
nameSelect="@fileName"
formatSelect="@format" />
</EmbeddedFiles>
</Config>
During processing, the file handler will then look for the following files in the incoming ZIP data:
files/image1.png
files/image2.png
If the payload itself does not point out the files, one may map files from the ZIP data instead.
To use this mode you need to set the useFileMapper
attribute on the <File>
element to true.
<File useFileMapper="true" ...>
When this mode is defined, you need to specify some additional mapping rules as child elements.
Child Element | Description | Required |
---|---|---|
|
Defines mapping rules, e.g. where to look for files in the incoming ZIP file in context of the current object being processed |
True |
|
Defines additional filtering rules, e.g. files to exclude/include |
False |
The <FileMapper>
element must contain at least one <PathItem>
element.
The path items together builds up the search path to the files to be processed.
The table below shows the accepted attributes on a path item element.
Attribute | Description | Example |
---|---|---|
value |
Defines a static path item name |
|
select |
Defines an XPath expression that will select a value from the current context in the XML data |
|
mapsToFormat |
May be used to define that the name of the path at this level specifies the format for the file |
|
ignoreMissing |
May be used to ignore missing item without throwing exception. Default is true. |
|
If neither the value nor the select attribute are defined, the path-item matches to any directory. |
Lets shown an example below:
│ payload.xml
│
└───files
├───TST-0001
│ ├───generic
│ │ file1.doc
│ │ file2.xls
│ │ file3.doc
│ │
│ └───JT
│ test1.jt
│ test2.jt
│
├───TST-0002
│ └───generic
│ SomeFile.xlsx
│
├───TST-0003
└───TST-0004
<Specs>
<Spec type="CAD Drawing" name="TST-0001" rev="A"/>
<Spec type="CAD Drawing" name="TST-0002" rev="A"/>
<Spec type="CAD Drawing" name="TST-0003" rev="A"/>
<Spec type="CAD Drawing" name="TST-0004" rev="A"/>
</Specs>
<CreateConfiguration
txType="update"
runPrivileged="true"
historyOff="true"
triggerOff="true">
<InputFormats>
<Zip>
<InputFiles>payload.xml</InputFiles>
</Zip>
</InputFormats>
<EntryPoint select="/Specs/Spec" />
<Config match="Spec">
<IfFound>Update</IfFound>
<IdentityMatch>
<Type select="@type" />
<Name select="@name" />
<Revision select="@rev"/>
</IdentityMatch>
<CreateValues>
<Policy fallbackValue="CAD Drawing"/>
<Vault fallbackValue="vault_eServiceProduction" />
</CreateValues>
<EmbeddedFiles>
<File reuseVersion="true"
formatFallback="generic"
useFileMapper="true"> (1)
<FileMapper> (2)
<PathItem value="files" />
<PathItem select="@name" />
<PathItem mapsToFormat="true" />
</FileMapper>
<FileFilter excludedFormats="JT" />
</File>
</EmbeddedFiles>
</Config>
</CreateConfiguration>
1 | The useFileMapper must be set to true |
2 | The <FileMapper> element specifies the path to the files. Note that a path item can contain static names or dynamic names selected from the XML data.
A path item may also contain the format name, thush the mapsToFormat attribute can be used to specify that. |
You may use so called value mappers to support translation of values. For example name of types or states may not be the same between two different systems.
You may define as many value mappers as you need, each is given an identifier, which you refer to on those fields representing values that needs to be translated.
The <ValueMapper>
element must have an attribute called id
containing a valid identifier.
Possible child elements to the <ValueMapper>
element are (note you may combine them as you need):
Child Element | Description |
---|---|
|
Defines a reference to an external mapping file (see below) |
|
Defines inline rules (see below) |
|
Custom value mappers. Requires attribute className pointing to
class that implements the interface |
Using value lookup:
The <ValueLookup>
element supports these attributes:
The name of the extrernal file.
If the name starts with file:, then the value is assumed to be a file from the
file system, where TIF is running. You may use macros like ${TIF.HOME}
to refer
to the root directory of the current TIF installation.
If the name does not start with file:, it is assumed to be a resource stored within
the ${TIF_ROOT}/modules/enovia/cfg/lookup
directory. If the file ends with
.properties
it is assumed to be a standard Java properties file, otherwise, if it ends
with .xml
it is assumed to be an XML file following this format:
<Properties>
<Property name="property-1" value="value1" />
<Property key="property-2" value="value2" />
<Property name="property-3">value 3</Property>
<Group key="group1">
<Property key="p1" value=".." /> <!-- accessed via key group1.p1 -->
</Group>
</Properties>
An extra string to be prepended to the value before performing the lookup
An extra string to be appended to the value before performing the lookup
Using inline rules:
The <If>
element can be used in the following way:
<ValueMapper id="...">
<If is="something" caseSensitive="false">replace value</If>
<If matches="a?c?e*">replace value</If>
<If beginsWith="abc">replace value</If>
<If endsWith="def">replace value</If>
<If regexp="...">replace value</If>
</ValueMapper>
The <Namespaces>
element can be used to configure the name-space context used when evaluating XPath expressions.
In case your incoming XML data contains namespace information, the XPaths may be difficult to define without the mapping of prefix/uri.
You can choose to either define all your Namespace mappings manually, or use the setting that will copy over the namespaces from the source document. The latter requires that you always know what prefixes are being used for the URIs.
To copy over the namespaces from the source (incoming data), then you should use the following attributes.
<CreateConfiguration>
<Namespaces mapFromSource="true" mapFromRootElementOnly="true" />
...
</CreateConfiguration>
The mapFromRootElementOnly
attribute is by default set to true, but in case your namespace declarations occurs later on in the document,
you may need to set this flag to false. That implies the whole document is being scanned for xmlns:
declarations.
If you prefer declaring the namespaces manually, you can use the following syntax.
<CreateConfiguration>
<Namespaces>
<Namespace prefix="a" uri="http://the_uri_for_a" />
<Namespace prefix="b" uri="http://the_uri_for_b" />
</Namespaces>
...
</CreateConfiguration>
This will give you exact control over the prefix/uri mapping.
If an object could not be mapped through the identity values, the create/update integration can be configured to revise an earlier revision.
First, one need to configure the <IfNotFound>
to revise. The default value for this setting is create.
When this mode is enabled, the create/update integration will try to find an object having the same TYPE and NAME as the object you try to match with.
Lets take an example. Below is a simple payload and a matching configuration.
<Object>
<Kind>Part</Kind>
<Identifier>TEST-000001</Identifier>
<Revision>C</Revision>
</Object>
<Config match="Object">
<IfFound>update</IfFound>
<IfNotFound>revise</IfNotFound> (1)
<IdentityMatch>
<Type select="Kind/text()" />
<Name select="Identifier/text()" />
<Revision select="Revision/text()" />
</IdentityMatch>
</Config>
If the object Part/TEST-000001/C does not exist, the create update integration will perform a query like below to find an object to revise.
temp query bus Part TEST-000001 * where "revision == last" limit 1
If this query does NOT return any result, the object is created in the same way
as if the <IfNotFound>
setting would have its value set to create.
If the query returns a result, that object is first revised and secondly, the revised object is updated according to configurations made.
Additional control over the revisioning can be specified using the <ReviseBehavior>
elment as
shown below:
<Config match="Object">
<IfFound>update</IfFound>
<IfNotFound>revise</IfNotFound>
<ReviseBehavior
reviseWithFile="true"
searchType="type_Part"
searchExpandType="true" />
</Config>
The attribute supported on the <ReviseBehavior>
element are:
Name | Description |
---|---|
reviseWithFile |
Defines the flag revise-with-file passed to the ENOVIA kernel upon revising the object. Default is FALSE. |
searchType |
Overrides the type used in the type pattern when quering for the revisions. By default we use the same type as the object you are targetting. Note however if your revision sequence may have objects of different type it may be useful here to specify a common root type that will be used in the query. |
searchVaultPattern |
Specifies a custom vault pattern, if you want to narrow the query over certain vaults. Default is all vaults. |
searchExpandType |
Whether or not to query for objects having a sub-type of the type used in the query. Default is TRUE. |
It is possible to as a part of the create/update integration use-case create the revision sequence on-the-fly. Example: you are requesting to create/update an object of revision E and you do not know if the past revisions are in the database. Hence you want to include information that there exists four earlier revisions and let the create/update integration create "placeholders" for these in the database.
Starting with an example, below is a payload snippet and a matching configuration snippet.
<Object>
<Kind>Part</Kind>
<Identifier>TEST-000002</Identifier>
<Revision>E</Revision>
<Revisions> (1)
<Rev value="A" state="Obsolete">description...</Rev>
<Rev value="B" state="Obsolete">description...</Rev>
<Rev value="C" state="Obsolete">description...</Rev>
<Rev value="D" state="Release">description...</Rev>
</Revisions>
</Object>
1 | The revisions are provided in this format (other format alternatives are supported) |
The create/config configuration below:
<Config match="Object">
<IfFound>update</IfFound>
<IfNotFound>revise</IfNotFound> (1)
<ReviseBehavior> (2)
<BuildSequence select="Revisions/Rev/@value"> (3)
<States select="Revisions/Rev/@state" />
<Descriptions select="Revisions/Rev/text()" />
</BuildSequence>
</ReviseBehavior>
1 | Remember to specify the if-not-found to revise |
2 | Supply <ReviseBehavior> to define advanced revisioning rules |
3 | The <BuildSequence> element is used to control the building of revision sequences. |
The attribute supported on the <BuildSequence>
element are:
Name | Required | Description |
---|---|---|
select |
Yes |
An XPath expression used to select the revisions. The XPath starts from the contextual object you currently are locate on. |
splitBy |
No |
If the select expression maps to a single value containing for example a comma separated list, you need to speficy the delimiter to split by here. |
order |
No |
If the list for some reason is provided in reverse order, you can specify the value "reverse" here to indicate so. |
Allowed (optional) child elements are
<States>
<Descriptions>
These elements are used to provide additional data to be used when creating the revision sequence. E.g. you may want to specify the states of the objects.
If a revision already exists in the database, the existing revision will not be updated regarding state or description, even though the data you provided is different. |
Both the <States>
and <Descriptions>
elements supports the exact same attributes as for the <BuildSequence>
element, described above.
The values selected for the revisions and the states and/or descriptions must have the same number of items. |
Below is an alternate payload and matching configuration:
<Object>
<Kind>Part</Kind>
<Identifier>TEST-000002</Identifier>
<Revision seq="A,B,C,D">E</Revision>
</Object>
<Config match="Object">
<IfFound>update</IfFound>
<IfNotFound>revise</IfNotFound>
<ReviseBehavior>
<BuildSequence select="Revision/@seq" splitBy=","/>
</ReviseBehavior>
<CreateConfiguration
txType="update"
runPrivileged="true"
historyOff="true"
triggerOff="true">
<EntryPoint select="/Data/Items/Item" />
<ValueMapper id="type-mapping">
<ValueLookup name="sap-key-values.properties" keyPrefix="type." />
</ValueMapper>
<Config match="Item">
<IfFound>Update</IfFound>
<IdentityMatch>
<Type select="@t" valueMapper="type-mapping" />
<Name select="@n" />
<Revision latest="true" fallbackValue="Release" />
</IdentityMatch>
<CreateValues>
<Revision firstInSequence="true" />
<State fallbackValue="Release" />
<Policy fallbackValue="policy_ECPart" />
<Owner fallbackValue="tiftest" />
<Originated select="@created" dateFormat="iso-date" />
<Vault fallbackValue="vault_eServiceProduction" />
</CreateValues>
<UpdateValues useForCreate="true">
<Attribute name="attribute_Weight" select="@w" ifNull="fail" />
<Description base64Encoded="true" select="Description/text()"/>
<RDO select="@rdo" />
</UpdateValues>
<Connections>
<Connection relationship="relationship_EBOM"
select="Item"
disconnectExisting="true">
<IdentityMatch>
<Relationship>
<Attribute
name="attribute_FindNumber"
select="@findNumber"/>
</Relationship>
</IdentityMatch>
</Connection>
<Connection relationship="relationship_ReferenceDocument"
typePattern=""
select="Specs/Doc"
disconnectExisting="true">
<IdentityMatch>
<Object>
<Name select="@docID" />
</Object>
</IdentityMatch>
<UpdateValues useForCreate="true">
<Attribute
name="attribute_DocumentClassification"
select="@classification" />
</UpdateValues>
</Connection>
</Connections>
</Config>
<Config match="Doc">
<IdentityMatch>
<Type fallbackValue="Document"/>
<Name select="@docID" />
<Revision fallbackValue="*"/>
</IdentityMatch>
<CreateValues>
<Policy fallbackValue="Document" />
<Vault fallbackValue="eService Production" />
</CreateValues>
</Config>
</CreateConfiguration>
In order to trigger a create/update configuration via REST call, you need to
create a REST service configuration within ${TIF_ROOT}/modules/enovia/cfg/restservice
.
Below is an example how to launch such use case without requiring any context object.
<Rest>
<DisplayName>EBOM Create/Update Service</DisplayName>
<ServiceName>ebom</ServiceName>
<Credentials containerManaged="true" />
<Create config="EBOM.xml" /> (1)
<Create config="EBOM.xml" payload="tvc:payload/test1.xml"/> (2)
</Rest>
1 | This points out the configuration tvc:createconfig/EBOM.xml |
2 | Alternative, when there is a need to generate custom response via payload configuration |
Below is an alternative REST service configuration showing how to use input/context object.
<Rest>
<DisplayName>EBOM Create/Update service (single level)</DisplayName>
<ServiceName>ebom-single-level</ServiceName>
<IdLocator type="tnr"> (1)
<Setting name="allowWildcards" value="false" />
</IdLocator>
<Credentials containerManaged="true" />
<Create config="EBOM-single-level.xml" />
</Rest>
1 | Here we require the type name and revision to be present on the URL. Note that alternative ways to map URL into id’s can be done. Please read the chapter describing configurable REST Services here. |
Using custom payload generation:
When you point out a custom payload, please note that you must use the "objectIdParam" attribute to lookup the correct ID´s. For relationships, use "relationshipIdParam" attribute instead.
<Payload rootElement="Response">
<XMLSpec>
<IncludeTableHeaders>false</IncludeTableHeaders>
<IncludeTableGroups>false</IncludeTableGroups>
<AddColumnId>false</AddColumnId>
<AddCellIndex>false</AddCellIndex>
<AddColumnRef>false</AddColumnRef>
<AddCellValueSize>false</AddCellValueSize>
<OmitCellValueElement>true</OmitCellValueElement>
<OmitRowAttributes>true</OmitRowAttributes>
<UseColumnName>true</UseColumnName>
<TableDataElement/>
<RowElement>${TYPE}</RowElement>
</XMLSpec>
<TableContent objectIdParam="createdObjectIds" outerElement="CreatedObjects"> (1)
<Table>tvc:table/PartBasic.xml</Table>
</TableContent>
<TableContent objectIdParam="updatedObjectIds" outerElement="UpdatedObjects"> (2)
<Table>tvc:table/PartBasic.xml</Table>
</TableContent>
<TableContent relationshipIdParam="createdRelationshipIds" outerElement="CreatedRelationships"> (3)
<Table>tvc:table/RelBasic.xml</Table>
</TableContent>
</Payload>
1 | Use id’s of created business objects |
2 | use id’s of updated business objects |
3 | use id’s of created relationships |
The available parameters are:
createdObjectIds
revisedObjectIds
updatedObjectIds
allObjectIds
createdRelationshipIds
updatedRelationshipIds
allRelationshipIds
In order to trigger a create/update integration via JMS, you need to
add a JSM message listener within the directory ${TIF_ROOT}/modules/enovia/cfg/jmslistener
.
Below is an example how to setup such a listener:
<JMSListener>
<Name>Create Update EBOM via JMS</Name>
<Destination id="jms-1" /> (1)
<WithContext user="..." /> (2)
<Handler type="CreateUpdateIntegration" /> (3)
<Arguments>
<Argument name="configuration" value="tvc:createconfig/EBOM.xml" /> (4)
<!-- Below: Extra optional parameters -->
<Argument name="payloadconfig" value="tvc:payload/EBOM_Response.xml" /> (5)
<Argument name="objectidparam" value="oid" /> (6)
<Argument name="responsemessagetype" value="text" /> (7)
</Arguments>
</JMSListener>
1 | This is the destination you will get messages from |
2 | If you want to run the integration as a certain user, specify so here |
3 | This will choose the correct message listener |
4 | Points out the create/update configuration to be used |
5 | Specify custom payload config used to produce the response |
6 | Specify custom header name to use for reading contextual object id |
7 | Type of return message, default is text. Use stream to force stream message |
Please see previous chapter for details regarding using a custom payload for creation of the response.
The response message is sent to the queue as specified within the Reply To header of the JMS Message.
|
It is also possible to trigger the create/update integration via file system integration.
To do so, you need to add a directory listener within the directory ${TIF_ROOT}/modules/enovia/cfg/directorylistener
.
Below is an example how to setup such a listener:
<tif:DirectoryListener
xmlns:tif="http://technia.com/TIF/DirectoryListener"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://technia.com/TIF/DirectoryListener http://products.technia.com/tif/schema/latest/DirectoryListener.xsd">
<tif:Name>Create Update EBOM via File</tif:Name>
<tif:Destination id="file-dest-in" /> (1)
<tif:WithContext user="tiftest" /> (2)
<tif:Handler type="CreateUpdateIntegration" /> (3)
<tif:Paths delete="true" /> (4)
<tif:Arguments>
<tif:Argument name="configuration" value="tvc:createconfig/EBOM.xml" /> (5)
<tif:Argument name="outputDestination" value="file-dest-out" /> (6)
<tif:Argument name="errorDestination" value="file-dest-err" /> (7)
<tif:Argument name="payloadconfig" value="tvc:payload/EBOM_Response.xml" /> (8)
</tif:Arguments>
</tif:DirectoryListener>
1 | This is the destination that configures the directory to listen for files from |
2 | If you want to run the integration as a certain user, specify so here |
3 | This will choose the correct directory listener that will trigger the integration correctly |
4 | Deletes the source file after completion |
5 | Points out the create/update configuration to be used |
6 | Defines a destination where the success response is written into. Note that the file-name remains the same as from the input directory. |
7 | Defines a destination where the error response is written into. Note that the file-name remains the same as from the input directory. |
8 | Specify custom payload config used to produce the response |
Please see previous chapter for details regarding using a custom payload for creation of the response.
Encoding of input and success/error response payload can be optionally defined as arguments.
For example:
...
<tif:Arguments>
<tif:Argument name="inputEncoding" value="UTF-8" /> (1)
<tif:Argument name="outputEncoding" value="UTF-8" /> (2)
</tif:Arguments>
</tif:DirectoryListener>
1 | Defines encoding of input payload. If not defined, default charset is used. |
2 | Defines encoding of success/error payload. If not defined, default charset is used. |
There are some possibilities within the create/update integration to plugin custom code in order to override certain behavior or add extra logic when something happens during the processing.
In order to listen to occurring events, one can specify a listener within the configuration as shown below.
Such listener must implement the interface com.technia.tif.enovia.integration.event.IntegrationListener
.
This interface has one method that you need to implement:
void handleEvent(IntegrationEvent event);
The event
argument passed may be an instance of:
com.technia.tif.enovia.integration.event.ObjectEvent
com.technia.tif.enovia.integration.event.RelationshipEvent
com.technia.tif.enovia.integration.event.FileEvent
com.technia.tif.enovia.integration.event.FailureEvent
com.technia.tif.enovia.integration.event.XMLParsedEvent
From the event object, you can get the event type, which is an enum constant with the following values
Enum Constant | Description |
---|---|
OBJECT_CREATED |
A business object was created |
OBJECT_REVISED |
A business object was revised |
OBJECT_UPDATED |
A business object was modified |
OBJECT_DELETED |
A business object was deleted |
RELATIONSHIP_CREATED |
A relationship was created |
RELATIONSHIP_UPDATED |
A relationship was modified |
RELATIONSHIP_DELETED |
A relationship was deleted |
FILE_CHECKEDIN |
A file was checked-in to a business object |
STARTED |
The integration started |
COMPLETED |
The integration is complete |
FAILURE |
The integration failed |
TRANSACTION_START_UPDATE |
An update transaction has been started |
TRANSACTION_START_READ |
A read transaction has been started (not commonly used) |
TRANSACTION_COMMITTED |
The transaction was committed |
TRANSACTION_ABORTED |
The transaction was aborted |
XML_PARSED |
The XML data has been parsed |
OTHER |
Other unspecified event |
If you want to abort the processing of the integration, you can always throw an unchecked exception, example:
package com.acme;
import com.technia.tif.core.TIFRuntimeException;
import com.technia.tif.enovia.integration.event.FailureEvent;
import com.technia.tif.enovia.integration.event.IntegrationEvent;
import com.technia.tif.enovia.integration.event.IntegrationListener;
import com.technia.tif.enovia.integration.event.ObjectEvent;
import com.technia.tif.enovia.integration.event.RelationshipEvent;
public class MyListener implements IntegrationListener {
@Override
public void handleEvent(IntegrationEvent event) {
switch (event.getType()) {
case OBJECT_UPDATED:
String oid = ((ObjectEvent) event).getObjectId();
if (getValueFromObject(oid).equals("Bad")) {
throw new TIFRuntimeException("Bad value detected. Aborting");
}
....
}
}
}
In order to register your listener, use the listener
attribute on the root element:
<CreateConfiguration listener="com.acme.MyListener" ...>
...
</CreateConfiguration>
During the processing of a create/update integration, the integration will at certain places try to find business objects from the database in order to map them to the incoming payload.
You may override the find logic by providing a class that implements the interface
com.technia.tif.enovia.integration.create.BusinessObjectFinder
. The default implementation
is com.technia.tif.enovia.integration.create.impl.DefaultBusinessObjectFinder
.
<CreateConfiguration>
...
<Config>
<ObjectFinder className="com.acme.MyFinder" />
...
</Config>
</CreateConfiguration>
A business object processor is involved for the creation, updating or revising an object.
You may override this logic by providing a class that implements the interface
com.technia.tif.enovia.integration.create.BusinessObjectProcessor
. The default implementation
is com.technia.tif.enovia.integration.create.impl.DefaultBusinessObjectProcessor
.
<CreateConfiguration>
...
<Config>
<ObjectProcessor className="com.acme.MyObjectProcessor" />
...
</Config>
</CreateConfiguration>
Similar to a business object processor, a relationship processor is used for the creation, updating and deletion of connections between business objects.
To override the default logic you can provide a custom class that implements the interface
com.technia.tif.enovia.integration.create.RelationshipProcessor
.
The default implementation is com.technia.tif.enovia.integration.create.impl.DefaultRelationshipProcessor
.
<CreateConfiguration>
...
<Config>
<Connections>
<Connection>
<RelationshipProcessor className="com.acme.MyRelProcessor" />
...
</Connection>
...
</Connections>
...
</Config>
</CreateConfiguration>
A file processor is responsible for the checkin file operation.
To override the default logic you can provide a custom class that implements the interface
com.technia.tif.enovia.integration.create.FileProcessor
.
The default implementation is com.technia.tif.enovia.integration.create.impl.DefaultFileProcessor
.
<CreateConfiguration>
...
<Config>
<FileProcessor className="com.acme.MyFileProcessor" />
...
</Config>
</CreateConfiguration>
When "TRACE" log level is enabled, create / update integration provides more information to TIF’s log file. This can be useful for testing and development purposes.
You may change run time log settings from Admin UI. See sections "Admin UI" and "TIF Core" / "Log Settings" in the documentation.
"TRACE" log level is not intended to be used in the production use as detailed logging might negatively affect the performance. |
A batch job in TIF is a job that typically performs some operation onto files and/or objects inside the ENOVIA™ database.
Example of batch job could be converting Microsoft Word document into PDF and apply a watermark upon release of the document object.
TIF provides functionality for performing batch operations on files checked in to ENOVIA™. The kind of operations supported are:
Converting Microsoft Word, Excel and Power Point files into PDF
Setting document properties on Microsoft Word, Excel and Power Point files
Adding watermark to PDF files
This feature has been part of TIF since its first release. However, the first implementation required the TIF instance performing the conversion jobs to be ran on a Windows machine. This first implementation is referred to as Modifier for Windows.
Now, TIF also contains an implementation in Java, which performs most of the operations within the JVM. Some operations could also be dispatched to an external process, for example invoking a program that does some conversion such as Adlib™. This implementation is referred to as Modifier for Java.
The next chapters describes the different implementations.
When using the File Modifier feature on a TIF instance running on Windows, the "windows" implementation is per default selected unless otherwise configured. On any other platform, the Java implementation will be the default and the Windows implementation cannot be chosen. |
By default, this functionality only works if TIF is running on a Windows based OS. If you are using Linux/UNIX OS’es and want to use this implementation, one option is to setup an additional TIF instance running on a Windows OS, and configure that TIF instance to process jobs from one dedicated queue. Then you just have to ensure that all jobs that are performing file modifications as describe in this page is using that dedicated queue.
If a Windows based OS is not available, switch to use the Java based implementation. See chapter Custom Java implementation below.
If you run TIF as a service, ensure that the following folders exists in the filesystem:
|
The following software needs to be installed on the server for PDF functionality:
|
Depending on the event that triggered a file modification job, the job may get information about one particular file from the business object in question to operate upon. That is for example the case if the job was initiated via a checkin-event. However, for other events that triggers the file modification job, TIF will then operate upon all files attached to the business object in question. |
To start with, below is an example job configuration showing how to utilize the file modification functionality.
<Job>
<Name>Convert to PDF</Name>
<FileModifier>
<FileFilter
includeFormats="generic,other"
excludeFileNames="*.pdf"/>
<!-- or
<FileFilter
excludeFormats="PDF"
includeFileNames="*.*"/> -->
<UpdateProperties>
<PropertyHandler>com.acme.foo.MyPropertyHandler</PropertyHandler>
<Property name="Property 1" selectExpression="type"/>
<Property name="Property 2" selectExpression="attribute[attribute_Foo]"/>
</UpdateProperties>
<CreatePDF>
<ExcelOptions>
<MarginTop>10</MarginTop>
<MarginRight>10</MarginRight>
<ScaleToFit>true</ScaleToFit>
</ExcelOptions>
</CreatePDF>
<PDFWatermark>
<Definition if="current == Released">
<Text>${current}</Text>
<FontSize>72</FontSize>
<FontColor>rgb(0,255,0)</FontColor>
<TextRotation>45</TextRotation>
</Definition>
<Definition>
<Text>NOT RELEASED (${current})</Text>
<FontSize>144</FontSize>
<FontColor>rgb(255,0,0)</FontColor>
</Definition>
<Checkin format="PDF" fileName="${name}.pdf"/>
</PDFWatermark>
</FileModifier>
<Events>
<Error>
...
</Error>
</Events>
</Job>
The example above will be executed only if the object (which the job is running against) has a file checked in under the format "generic" or "other" and not ending with ".pdf". Shortly, what happens in this case is:
The example here illustrates the usage of a custom class defining key/values to set as well as defining properties mapped to select-expression.
If the source file is an Excel file then there are some additional settings available for handling margins / scaling.
A watermark is applied to the PDF file and the final PDF file is checked-in to ENOVIA under the PDF format. The actual watermark text is selected based upon the if condition.
The root tag in the definition is always <Job>
.
The first child element of the Job element defines the kind of job,
in this case we will use the <FileModifier>
element to define the use of the file modification functionality.
Below the FileModifier element, the following child elements are available.
<FileFilter>
Defines what files to perform operation upon.
<UpdateProperties>
Defines that the document properties shall be updated
<CreatePDF>
Converts the Office document into PDF
<PDFWatermark>
Applies a PDF watermark to the PDF file
The child pages will go through the configuration possibilities in more detail.
File modification jobs support job events for handling errors etc. Read more in the Job Events chapter.
The <FileFilter>
element is used to define what files to operate on. A business object may have several files attached and they may be attached into different formats (ENOVIA™ feature).
On the <FileFilter>
element, you have a couple of attributes that can be used to define either inclusion rules or exclusion rules. See table below:
Attribute | Description |
---|---|
includeFormats |
Comma separated list of formats to accept |
excludeFormats |
Comma separated list of formats to reject |
includeFileNames |
Comma separated list of file name patterns to accept |
excludeFileNames |
Comma separated list of file name patterns to reject |
if |
Comma separated list of parameter names that should be present in order for the filter to accept the file. The parameters are resolved from the originating job. |
unless |
Comma separated list of parameter names that NOT must be present in order for the filter to accept the file. |
The values of the parameter specified in either the if and/or unless attribute are not relevant. We are only checking the presence of such parameter.
|
Example:
<Job>
<FileModifier>
<FileFilter
if="special.condition"
includeFormats="format_Generic,format_SomeOther,format_AThirdFormat"
includeFileNames="*.doc,*.docx"/>
The patterns are case insensitive. |
The <UpdateProperties>
element defines that you want to update the document properties on the file (only for Microsoft Office™ files such as Word™, Excel™, Powerpoint™).
You may point out a Java class that provides the properties (key/value pairs) to set and/or define in the configuration properties mapped to some select expression that in turn gives the value for the property.
The possible child elements are listed in the table below:
Child Element | Description | Example |
---|---|---|
|
Defines a single property to be transferred to the document. |
|
|
Defines that the default property handler provided by TIF shall be used. |
|
|
Points out a Java class implementing the interface |
<PropertyHandler>com.acme.integrations.file.SetProperties</PropertyHandler> |
|
If you want to check-in the document after the properties has been set, use this element to do so. |
|
Property
Defines a property to be transferred.
Example
<UpdateProperties>
<Property name="Type" selectExpression="${attribute[attribute_ProductType]}"/>
<Property name="Status" selectExpression="current"/>
</UpdateProperties>
Default Properties
This element uses a default property handler available inside TIF. This property handler will extract a large amount of properties from the business object and propagate it to the file.
This property handler provides the same/similar properties as done in the TVC File Manager application.
The prefix and suffix attributes are optional and may be used to add a prefix/suffix to the property name.
Custom Property Handler
The interface com.technia.tif.enovia.job.executors.file.PropertyHandler
is defined as below:
package com.technia.tif.enovia.job.executors.file;
import java.util.Map;
import com.technia.tvc.core.TVCException;
public interface PropertyHandler {
/**
* Returns the properties for a specific file/object/format combination.
*
* @param objectId The ID of the business object, which the file belongs to.
* @param format The format, which the file is being checked in to
* @param fileName The name of the file
* @return A {@link Map} containing string keys and values representing the
* properties to transfer
* @throws TVCException When some ENOVIA-DB communication occurs.
*/
Map<String, String> getProperties(String objectId, String format, String fileName) throws TVCException;
}
Checkin
Optionally, you may want to checkin the file containing the modified properties. If so, then use the <Checkin>
element for that.
Without any attributes specified, the file will be checked in using the same name and format. If the file is checked-in to a CDM object (Common Document Model) a new version will be created unless the "overwrite" attribute has been set to true.
Supported attributes are:
The file name to check-in to (if undefined, same file name is used).
Note that you may use the following macros:
${filename}
: the original filename (full name)
${name}
: the original filename excluding the file extension
${ext}
: the original file-extension
The format to check-in to (if undefined, same format is used).
Boolean (default is false) specifying if to overwrite the current version with the modified file. False causes a new version (CDM version) to be created.
The <CreatePDF>
element defines that you want to convert the Microsoft Office file into a PDF file.
The possible child elements are listed in the table below:
Child Element | Description | Example |
---|---|---|
|
Defines additional options that applies to conversion of a Microsoft Excel file into PDF |
|
|
Defines if the ISO standardized PDF format (archive) should be used. |
+
|
|
If you want to check-in the generated PDF file, use this element to do so |
|
Excel Options
The ExcelOptions element can have the following child elements:
Child Element | Description | Example |
---|---|---|
|
Defines the top margin |
|
|
Defines the right margin |
|
|
Defines the bottom margin` |
|
|
Defines the left margin` |
|
|
Page orientation for the PDF file. Possible values are "landscape" and "portrait" |
|
|
A boolean specifying if to scale the Excel sheet to fit the PDF page |
|
Checkin
See above.
The <PDFWatermark>
is used to define how to generate (or add) watermarks onto a PDF file.
You may have several watermark definitions and depending on some condition of the business object, for example if the object itself is in a particular state you may want to use a different watermark definition than in other cases.
This is implemented by allowing you to specify an ENOVIA™ expression that should evaluate to true on the current business object holding the PDF file.
The possible child elements are listed in the table below:
Child Element | Description | Example |
---|---|---|
|
Contains the watermark definition (specified by child elements). You may add several "Definition" elements using different "conditions". Note that the first Definition whose condition evaluates to true on the current business object will be used. |
|
|
If you want to check-in the generated PDF file, use this element to do so. |
|
Definition
The <Definition>
element may have an attribute named "if" containing an ENOVIA™ expression, which if evaluated to TRUE for the current business object result then is used to create the watermark.
The expression itself must be a valid ENOVIA™ expression and you can test your expression from for example MQL via the following syntax:
print businessobject 1.2.3.4 select evaluate[YOUR EXPRESSION] dump;
example:
<MQL> print businessobject 1.2.3.4 select evaluate[current matchlist 'Release,Approved' ','] dump;
If you omit the "if" attribute or let it be empty, it will evaluate to TRUE for any business object.
The <Definition>
elements are evaluated in the order they are defined.
The possible child elements are listed in the table below:
Child Element | Description | Example |
---|---|---|
|
Contains the text definition. You may mix static text along with macros referring to select statements that will be evaluated against the business object holding the file. Alternate to static text along with macros is to point out a custom Java class that provides the text. The class must implement the interface |
|
|
The name of the font to be used. Default is Arial |
|
|
The size of the font to be used. Default is 50. |
|
|
Defines the color of the font. Different ways of specifying the color is supported, for example:
The default color is black. |
|
|
Defines the rotation in degrees. -360 - 360 are allowed values. Default value is 0. |
|
|
Defines the transparency of the watermark. Allowed values are in the range 0 to 255. Default is 255. |
|
|
Number of times the text is printed between (start-x, start-y) and (end-x, end-y). Default is 1. |
|
|
Start position on X-axis. Valid value is a percentage between 0 and 100. Default is 50. |
|
|
Start position on Y-axis. Valid value is a percentage between 0 and 100. Default is 50. |
|
|
End position on X-axis. Valid value is a percentage between 0 and 100. Default is 50. |
|
|
End position on Y-axis. Valid value is a percentage between 0 and 100. Default is 50. |
|
Checkin
See above
Custom Text Provider
The interface com.technia.tif.enovia.job.executors.file.TextProvider
is defined as below:
package com.technia.tif.enovia.job.executors.file;
import com.technia.tif.enovia.job.EnoviaJob;
import com.technia.tvc.core.TVCException;
public interface TextProvider {
/**
* Returns text for a specific job/file/object/format combination.
*
* @param job Job object
* @param objectId The ID of the business object, which the file belongs to.
* @param format The format, which the file is being checked in to
* @param fileName The name of the file
* @return Text
* @throws TVCException When some ENOVIA-DB communication occurs.
*/
String getText(EnoviaJob job,
String objectId,
String format,
String fileName) throws TVCException;
}
Instead of using TIF’s built-in Windows based file modifier, it is possible to run File Modifier via Java implementations / via external processes such as Adlib PDF Converter or Libre Office PDF converter.
To enable Java implementation, the attribute type
must be present with value
java
in the configuration element FileModifier
. On non Windows platforms, this
is however not needed, since the Java implementation is the default selected.
However, for clarity it is recommended to specify that.
The default implementations in Java are implemented as described below:
Uses the Apache POI library to set document properties.
Invokes an external process for the creation of the PDF document. For example you can use Adlib PDF converter or Libre Office to conduct the conversion.
Uses the Java library iText (version 2.1) for applying the watermark.
Below is a complete example illustrating how to use the Java file modifier
<Job>
<Name>PDF Converter</Name>
<FileModifier type="java">
<FileFilter
includeFormats="generic"
includeFileNames="*.docx"/>
<UpdateProperties>
<DefaultProperties prefix="MX" suffix=""/>
<Checkin fileName="${filename}"/>
</UpdateProperties>
<!-- NOTE: Use one of the below CreatePDF elements -->
<CreatePDF implementation="adlibPDFConverter">
<Input destinationId="adlib-in-folder" />
<Output destinationId="adlib-out-folder" />
<Error destinationId="adlib-err-folder" />
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
<!-- OR Use this: -->
<CreatePDF>
<Command>C:/Program Files/LibreOffice/program/soffice.exe</Command>
<Command>--headless</Command>
<Command>--convert-to</Command>
<Command>pdf</Command>
<Command>${file}</Command>
<Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
<Timeout>60000</Timeout>
<OutputFile>${fileprefix}.pdf</OutputFile>
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
<PDFWatermark allowMultiple="true">
<Definition if="current == 'Preliminary'">
<Text>${current}</Text>
<FontSize>30</FontSize>
<FontColor>rgb(255,0,0)</FontColor>
<TextRotation>-45</TextRotation>
<StartX>15</StartX>
<StartY>15</StartY>
<TextTransparency>50</TextTransparency>
<Count>1</Count>
</Definition>
<Definition if="current == 'Released'">
<Text>RELEASED</Text>
<FontSize>50</FontSize>
<FontColor>rgb(0,255,0)</FontColor>
<TextRotation>45</TextRotation>
<StartX>15</StartX>
<StartY>15</StartY>
<TextTransparency>70</TextTransparency>
<Count>1</Count>
</Definition>
<Checkin fileName="${filename}.pdf"/>
</PDFWatermark>
</FileModifier>
</Job>
Follows the same format and syntax as described above for the Windows File Modifier implementation. The difference is that this implementation performs the property update using the Apache POI library.
See Update Properties above.
Create PDF will per default assume that you use an external program that converts the input file to PDF.
E.g. the attribute implementation="externalFileConverter"
on the <CreatePDF>
element
is the default value unless otherwise specified.
Starting with an example below:
<Job>
...
<FileModifier type="java">
...
<CreatePDF>
<Command>/opt/LibreOffice/program/soffice</Command>
<Command>--headless</Command>
<Command>--convert-to</Command>
<Command>pdf</Command>
<Command>${file}</Command>
<Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
<Timeout>60000</Timeout>
<OutputFile>${fileprefix}.pdf</OutputFile>
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
</FileModifier>
...
</Job>
There is a legacy format accomplishing the same, which is shown below for reference.
<Job>
...
<FileModifier type="java">
<CreatePDF implementation="externalFileConverter">
<Arg name="commands" value="C:/Program Files/LibreOffice/program/soffice.exe;--headless;--convert-to;pdf;${file}" />
<Arg name="extensions" value="doc;docx;xls;xlsx;ppt;pptx" />
<Arg name="timeout" value="60000" />
<Arg name="outputFile" value="${fileprefix}.pdf" />
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
</FileModifier>
...
</Job>
You can also configure default configurations within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.
These will be used in case you omit something in the Job Configuration itself.
E.g. if you don’t specify any command in the job configuration, TIF will look for such in the property file.
# A ; separated list of allowed file extensions
externalFileConverter.extensions=
# A ; separated list containing commands to launch converter process with arguments
externalFileConverter.commands=
# Converter process timeout in milliseconds
externalFileConverter.timeout=
# Expected output file name after conversion
externalFileConverter.outputFile=
Supported macros in the configuration:
Macro | Description |
---|---|
${file} |
Input file name |
${fileprefix} |
Input file name prefix (for example: test.docx → test) |
${filesuffix} |
Input file name suffix (for example: test.docx → docx) |
${iso} |
Value of configuration element <ISO> |
${scaletofit} |
Value of configuration element <ScaleToFit> |
${marginbottom} |
Value of configuration element <MarginBottom> |
${marginleft} |
Value of configuration element <MarginLeft> |
${marginright} |
Value of configuration element <MarginRight> |
${margintop} |
Value of configuration element <MarginTop> |
Below are examples how to configure externalFileConverter
to call LibreOffice in headless mode to convert MS Office document to PDF and finally check in the converted PDF.
Example 1: Job configuration and module.custom.properties
Job configuration:
<Job>
...
<FileModifier type="java">
<CreatePDF implementation="externalFileConverter"> (1)
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
</FileModifier>
</Job>
1 | Implementation attribute can be omitted, since the external file converter is the default implementation. |
${TIF_ROOT}/modules/enovia/etc/module.custom.properties
:
externalFileConverter.extensions=doc;\
docx;\
ppt;\
pptx;\
xls;\
xlsx
externalFileConverter.commands=C:/Program Files/LibreOffice/program/soffice.exe;\
--headless;\
--convert-to;\
pdf;\
${file}
externalFileConverter.timeout=60000
externalFileConverter.outputFile=${fileprefix}.pdf
Example 2: Job configuration with everything configured in the job configuration
<Job>
...
<FileModifier type="java">
<CreatePDF>
<Command>/opt/LibreOffice/program/soffice</Command>
<Command>--headless</Command>
<Command>--convert-to</Command>
<Command>pdf</Command>
<Command>${file}</Command>
<Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
<Timeout>60000</Timeout>
<OutputFile>${fileprefix}.pdf</OutputFile>
<Checkin fileName="${filename}.pdf"/>
</CreatePDF>
</FileModifier>
</Job>
If you have Adlib PDF converter available, an option is to use the Adlib folder connector for PDF conversion.
To use this, you need to set the attribute implementation="adlibPDFConverter"
on the <CreatePDF>
element.
Below is an example how to configure this:
<Job>
<Name>PDF Converter</Name>
<FileModifier type="java">
<FileFilter
includeFormats="generic"
includeFileNames="*.docx"
excludeFileNames="*.pdf"/>
<CreatePDF implementation="adlibPDFConverter"> (1)
<Input destinationId="adlib-in-folder" /> (2)
<Output destinationId="adlib-out-folder" />
<Error destinationId="adlib-err-folder" />
<PollTimeout>5000</PollTimeout>
<MaxTimeout>600000</MaxTimeout>
</CreatePDF>
</FileModifier>
</Job>
1 | You can either use the element <AdlibPDFConverter> or saying <CreatePDF implementation="adlibPDFConverter"> . The result is equal. |
2 | The Input, Output and Error element accepts either a destinationId attribute OR a path attribute.
The destinationId refers to a File destination with the given id inside the destinations.xml file. |
The poll timeout and max timeout are default set to 5 seconds and 10 minutes. Override if necessary. Note that the times are defined in milliseconds.
The PDF Watermarking implementation used when the Java file modifier is chosen, is using the iText/Lowagie library that is part of the TVC-Core library to conduct the watermarking.
Absolution positioning of watermark
By default, start and end positions of watermark are configured relatively as percentages.
lowagiePdfWatermark
additionally supports absolute positioning of watermark.
To enable it, set the attribute position
to absolute
on the elements <StartX>
, <StartY>
, <EndX>
and/or <EndY>
.
Use a decimal value to define position.
Default value for position
is relative
, if not set.
Multiple watermarks
This implementation can stamp multiple watermarks (in opposite to the Windows file modifier implementation).
To enable it, set the boolean attribute allowMultiple
to true
on the <PDFWatermark>
element.
When allowMultiple
is set to true
, all watermarks are stamped of which <Definition>
is evaluated to TRUE.
For example:
<Job>
...
<FileModifier type="java">
...
<PDFWatermark allowMultiple="true">
...
<Definition>
...
<!-- Absolute position -->
<StartX position="absolute">10.0</StartX>
...
<!-- Relative position -->
<StartY>20.0</StartY>
</Definition>
...
<Definition>
...
</Definition>
</PDFWatermark>
</FileModifier>
...
</Job>
The elements <UpdateProperties>
, <CreatePDF>
and <PDFWatermark>
all supports
overriding its default functionality by setting a className
attribute pointing to a
class that extends from com.technia.tif.enovia.job.executors.file.FileAction
.
For example:
<Job>
...
<FileModifier type="java">
<UpdateProperties className="com.acme.tif.CustomUpdateProperties">
</UpdateProperties>
<CreatePDF className="com.acme.tif.CustomCreatePDF">
</CreatePDF>
<PDFWatermark className="com.acme.tif.CustomPDFWatermark">
</PDFWatermark>
</FileModifier>
...
</Job>
The base class have one method that is required to be implemented:
import com.technia.tif.enovia.job.executors.file.FileActionContext;
import com.technia.tif.enovia.job.executors.file.FileActionResult;
protected FileActionResult process(FileActionContext ctx) throws Exception;
The FileActions part of TIF is available in source code format. See below:
If you have the TVC Report Generator or the ENOVIA RPT component available, you may let TIF perform the creation of the reports.
This will replace the need to using som called Report Daemon/Agents and let TIF also handle this.
To setup a Report Daemon inside TIF you configure this within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
.amp
The syntax is shown below.
reportGeneratorQueue.<ID>.enabled = true
reportGeneratorQueue.<ID>.queue = Test Queue
reportGeneratorQueue.<ID>.threadCount = 1
reportGeneratorQueue.<ID>.sleepInterval = 15000
For each queue you need to setup one block like above, each block must have its own unique <ID>.
In the Report Generator you may also configure a Queue to keep it’s job and additionally define a time period for how long the Jobs will be kept after completion. In such case, you can easily setup a cleaning routine with TIF to remove those jobs that are out-of-date.
This is examplified below.
<timetable>
<group id="maintenance">
<report-job-cleanser> (1)
<schedule>
<hour>2</hour>
<minute>0</minute>
<second>0</second>
</schedule>
</report-job-cleanser>
</group>
</timetable>
1 | Special tag that is used to enable the report job cleanser routine |
TIF provides support for running jobs at a scheduled time or period.
The scheduled jobs are defined within a file called timetable.xml
within the directory ${ROOT_DIR}/modules/enovia/etc
.
You can have instance specific timetable definitions. This is accomplished by adding more timetable files, within the same directory, following this naming convention:
timetable-{node-id}-{instance-id}.xml
timetable-{instance-id}.xml
timetable.xml
The file names are case insensitive |
TIF does not contain any timetable files per default.
However, a sample file called timetable.xml.sample
is provided in the same directory containing information and examples how to register scheduled jobs.
The root element of the XML file is <timetable>
.
Below this element you may have the following elements:
group
job
Jobs may be put into groups or un-grouped. Within the group element you may only have "job" elements.
The <group>
element must have an attribute called "id" containing the ID of the group (unique among all groups).
An example is shown below:
<timetable>
<job id="job1">...
<job id="job2">...
<group id="g1">
<job id="job3">...
<job id="job4">...
...
</group>
<group id="g2">
<job id="job5">...
</group>
</timetable>
The <job>
element defines the details of the scheduled job. You may configure a job to do one of the below
Execute a Java class
Execute a Script
Execute a MQL statement
Execute / Run a Job definition
The job element must have one attribute called "id" containing a unique identifier for the job.
The possible child elements for the job element is shown in the table below:
Child Element | Description | Required | Example |
---|---|---|---|
|
Used to provide the job with arguments |
No |
|
|
Defines when the job is executed. A cron format is used for specifying the time/period. See below for details. |
Yes |
|
|
Executes a Java class. See below for details |
|
|
|
Executes a script file. See below for details |
|
|
|
Executes a MQL statement (or statements) |
|
|
|
Executes a TIF job. Note that a TIF job typically requires an object as input, hence you need also some kind of "id provider" mechanism. See below for details |
|
One of java, script, mql or jobcfg is required. |
The arguments section are used to pass in arguments to the job. The syntax below is used.
<args>
<arg name="the name" value="the value" type="string | int | integer | long | real | double | bool | boolean | float"/>
...
</args>
The <schedule>
element defines when the job should be executed.
This element may have the following child elements.
<schedule>
<second>..</second>
<minute>..</minute>
<hour>..</hour>
<day-of-month>..</day-of-month>
<month>..</month>
<day-of-week>..</day-of-week>
<year>..</year>
</schedule>
|
Field Name | Allowed Values | Allowed Special Characters |
---|---|---|
second |
0-59 |
,-*/ |
minute |
0-59 |
,-*/ |
hour |
0-23 |
,-*/ |
day-of-month |
1-31 |
,-*?/LW |
month |
1-12 or JAN-DEC |
,-*/ |
day-of-week |
1-7 or SUN-SAT |
,-*?/L# |
year |
1970-2099 |
,-*/ |
Special characters:
* ("all values") - used to select all values within a field.
? ("no specific value") - useful when you need to specify something in one of the two fields in which the character is allowed, but not the other.
- Used to specify ranges. For example, "10-12" in the hour field means "the hours 10, 11 and 12".
, Used to specify additional values. For example, "MON,WED,FRI" in the day-of-week field means "the days Monday, Wednesday, and Friday".
/ Used to specify increments. For example, "0/15" in the seconds field means "the seconds 0, 15, 30, and 45".
L ("last") - has different meaning in each of the two fields in which it is allowed.
For example, the value "L" in the day-of-month field means "the last day of the month".
If used in the day-of-week field by itself, it simply means "7" or "SAT".
But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example "6L" means "the last friday of the month".
W ("weekday") - used to specify the weekday (Monday-Friday) nearest the given day.
As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month".
# used to specify "the nth" XXX day of the month. For example, the value of "6#3" in the day-of-week field means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month).
Other examples: "2#1" = the first Monday of the month and "4#5" = the fifth Wednesday of the month.
The 'L' and 'W' characters can also be combined in the day-of-month field to yield 'LW', which translates to "last weekday of the month".
To execute a Java class, use the <java>
element to specify your class to be executed.
This class must implement the interface com.technia.tif.enovia.scheduling.ScheduledJob
,
which is defined like this:
package com.technia.tif.enovia.scheduling;
public interface ScheduledJob {
void execute(JobContext ctx) throws Exception;
}
The JobContext argument is defined like this:
package com.technia.tif.enovia.scheduling;
import java.util.Iterator;
import java.util.Map;
public interface JobContext {
String getId();
String getGroupId();
Iterator<String> getParamNames();
String[] getValues(String name);
String getValue(String name);
Integer getIntValue(String name);
Double getDoubleValue(String name);
Long getLongValue(String name);
Boolean getBoolValue(String name);
Map<String, String[]> toParamMap();
}
Custom classes are placed inside some JAR file within the ${TIF_HOME}/modules/enovia/lib/custom
directory.
You may instead of implementing a Java class implement the scheduled job in a script file.
Within the <script>
element, point out the script file to be executed. For example:
<script>tvc:script:background/Job1.js</script>
This would refer to the file
${TIF_ROOT}/modules/enovia/cfg/background/script/Job1.js
The script must have a function like below:
function execute(jobCtx, objectIds) {
}
The last argument may be optional and might be null depending on if an "idProvider" attribute has been set on the script element.
Example with id provider:
<script idProvider="tvc:dataset:background/FindSomeObjects.xml">
tvc:script:background/JobThatDoesSomethingWithObjectsInEnovia.js
</script>
The <mql>
element may be used if to execute MQL or MQL/TCL code in the ENOVIA™ database.
See below for configuration details:
<mql>
execute program BackgroundJob;
</mql>
or
<mql idProvider="tvc:dataset:background/SomeDataSet.xml" tcl="true">
mql delete bus ${OBJECTID}
</mql>
The attributes available on the <mql>
element are:
Points out an ID provider, for example a data set that returns the objects used as input.
Note the usage of the macro ${OBJECTID} in conjunction with the use of an idProvider. The MQL code is executed once for each object found by the "id provider" and the macro is replaced with the actual object-id value.
True if the code is MQL/TCL.
True if to resolve any symbolic names prior to running the code.
The <jobcfg>
element may be used to launch an existing Job configuration.
See below for configuration details:
<jobcfg idProvider="tvc:dataset/MyDataSet.xml">
tvc:jobcfg/SomeJobConfig.xml
</jobcfg>
The job defined by the configuration is executed once per object found by the "id provider".
When executing integration jobs a number of events are triggered, e.g. when starting the job, successfully completing it and when an error occurs. There are built-in support to send e-mail and notifications upon the events. This is useful for instance to send e-mails to the support team in case an integration fails or notify the user initiating a job that it has finished. It’s also supported to provide a custom handler which handles custom logic, e.g. promote the ECO in case the job is successful.
Job events are configured for each integration service. They are supported for all job using jobcfgs, e.g. TransferData, FileModification and custom jobs.
Handlers can be combined. You can both send an e-mail and provide one or more custom handlers. |
The type of events the handlers can react on.
Triggered before the job starts.
Triggered when (and if) a job has been successfully executed.
Triggered when a job fails.
Sends an e-mail to the person initiating the integration job and/or other persons.
Element name: <Mail>
Available sub elements:
Element | Description |
---|---|
|
Defines the users to send the e-mail to. Use e-mail address. |
|
Defines the users to add as CC on the e-mail. Use e-mail address. |
|
Defines the users to add as BCC on the e-mail. Use e-mail address. |
|
Subject of e-mail |
|
Message of e-mail |
|
Content type of e-mail |
Notifications requires that the TVC Collaboration component is installed. |
Sends a notification to the person initiating the integration job and/or other persons. The notification is displayed directly in the ENOVIA UI in a similar way as when you receive an e-mail in Outlook. All notifications sent to you can be viewed in the Inbox. It’s also possible to view notifications related to for instance a Product by navigating to it and expanding the Collaboration Panel.
This feature creates messages and notifications in the TVC Collaboration component. More details on how to configure the Collaboration Panel, Inbox and searching is available in the TVC Collaboration Administration Guide.
Element name: <Notification>
Available sub elements:
Element | Description |
---|---|
|
Defines users to send notification to. Use the user name. |
|
Defines users to add as CC to the notification. Use the user name. |
|
Defines users to add as BCC to the notification. Use the user name. |
|
Subject of the notification |
|
Message of the notification |
|
Defines system tags to stamp on notification. Add one or more |
To configure who to send notifications from are done within the ${TIF_ROOT}/modules/enovia/etc/module.properties
.
The following properties
# Enable/disable notifications globally for TIF
notification.enabled = true
# User name to send notifications from. Notification sent from yourself are not displayed.
notification.from.userName = User Agent
# Relates the notification message to the source object for the integration job
notification.relateToObject = true
The "from user" needs a Person business object in the database. |
The notifications are broadcasted from the TIF application server to the app server which the user is logged in on. TVC Collaboration is using sensible defaults making it work in most cases. More details on how its configured is available in the Collaboration Admin Guide. |
Notifications sent from yourself are not displayed. I.e. notifications sent by "Test Everything" is not displayed to a user logged in as "Test Everything". |
Creates and executes a new job.
Available configuration attributes:
Attribute | Description | Required |
---|---|---|
|
Job configuration for new job. |
Yes |
|
Points out an id provider, either a data set or a custom Java class that returns object id used as input for new job. |
No |
|
Boolean flag that indicates if the object id from the parent job is used as input for new job. If |
No |
|
Specifies the minimum number of object ids the id provider is allowed to return. Default value is 0. |
No |
|
Specifies the maximum number of object ids the id provider is allowed to return. The value -1 means unlimited. Default value is 1. |
No, unless |
|
Points out a custom Java class that returns map of job parameters used as input for new job. |
No |
|
Boolean flag that indicates if the job parameters from the parent job are used as input for new job. If |
No |
|
Points out a custom Java class that evaluates whether a new job should be created or not. |
No |
Available configuration sub elements:
Element | Description | Required |
---|---|---|
|
Specifies job parameters for new job. Add one or more |
No |
An example configuration that uses object id and job parameters from the parent job:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" copyObjectId="true" copyParams="true" />
</Success>
</Events>
</Job>
Another example that includes job parameters specified:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" ...>
<Params>
<Param name="My First Param" value="some value" />
<Param name="My Second Param" value="first value; second value" />
</Params>
</NewJob>
</Success>
</Events>
</Job>
The new job is executed synchronously within the same thread as the parent job. In practice, the thread is released and the parent job is completed after all jobs created by <NewJob>
are executed and completed or if those are pending or awaiting reply. Retries and replies are executed in a separate thread.
If new jobs are created upon <Start>
event, they are executed first. The parent job continues with the execution after new jobs are marked with status completed, pending or awaiting reply.
It is not recommended to mass create new jobs if the parent job is initiated by a single threaded job queue listener, as it might block pending jobs in the queue. |
Id provider can be either a data set or a custom Java class that returns object ids used as input for new job.
New job is created for each object id returned by the provider. To prevent creating number of jobs unintentionally, the provider is allowed to return only one object id by default. You may override the restriction with settings minAllowedIds and maxAllowedIds .
|
An example configuration with dataset:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" idProvider="tvc:dataset/MyDataSet.xml" />
</Success>
</Events>
</Job>
An example configuration with custom Java class:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" idProvider="com.acme.tif.MyIdProvider" />
</Success>
</Events>
</Job>
The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.ObjectIdProvider
:
public interface ObjectIdProvider {
/**
* Returns an array containing object ids.
*
* @param event Job event
* @param jobcfg Jobcfg for new job.
*
* @return An array of object ids.
*/
String[] getIds(JobEvent event, String jobcfg) throws TVCException;
}
Job parameter provider is a custom Java class that returns map of job parameter used as input for new job.
An example configuration:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" paramProvider="com.acme.tif.MyParamProvider" />
</Success>
</Events>
</Job>
The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.JobParamProvider
:
public interface JobParamProvider {
/**
* Returns map containing job parameters.
*
* @param event Job event
* @param jobcfg Jobcfg for new job.
* @param objectId Object id for new job.
*
* @return Job parameters.
*/
public Map<String, String[]> getParams(JobEvent event, String jobcfg, String objectId) throws TVCException;
}
The provider is called separately for each jobcfg and object id combination.
By default, <NewJob>
does not allow to create new job with the same jobcfg as parent job.
To override this, it is possible to specify a custom Java class that evaluates whether or not new job should be created, based on input.
The default behavior prevents a possible infinite loop by not allowing to create and execute new job with the same jobcfg endlessly. It is important to prevent it in your custom code! |
An example configuration:
<Job>
...
<Events>
<Success>
<NewJob jobcfg="tvc:jobcfg/MyJob.xml" evaluator="com.acme.tif.MyNewJobEvaluator" />
</Success>
</Events>
</Job>
The custom class needs to implement the interface com.technia.tif.enovia.jobevent.newjob.NewJobEvaluator
:
public interface NewJobEvaluator {
/**
* Evaluates if new job should be created.
*
* @param event Job event
* @param jobcfg Job cfg
* @param objectId Object id for new job
* @param params Job parameters for new job
*
* @return True if job should be created, false if not.
*/
boolean evaluateNewJob(JobEvent event, String jobcfg, String objectId, Map<String, String[]> params) throws TVCException;
}
Provides to possibility to configure a custom java class containing custom logic. You can for instance promote the object in case the integration is successful. Specify the qualified java class name as text of the element.
The provided java class needs to implement the interface JobEventListener
.
Specify a custom handler by adding an element with the name <Handler>
and provide the qualified name of the java class in the attribute className
.
public interface JobEventListener {
/**
* Invoked when event occurs.
*
* @param event Event data
* @since 2015.3.0
*/
void onJobEvent(JobEvent event);
}
Example configuration:
<Job>
...
<Events>
<Start>
<Handler className="com.company.acme.tif.StartHandler" />
</Start>
</Events>
</Job>
The method onJobEvent(JobEvent)
is executed once per event type (start/success/error).
Implement the interface com.technia.common.xml.XMLReadable if your handler support configuration settings.
|
By default, exceptions thrown from handler are ignored. This can be changed with boolean attribute ignoreErrors
.
For example:
<Handler className="com.company.acme.tif.StartHandler" ignoreErrors="false" />
If not defined, the default value is true
.
You may throw any unchecked exception from handler. |
The table below lists event types and difference on behavior when an exception is thrown from handler:
Event Type | Errors ignored | Errors NOT ignored |
---|---|---|
Start |
Job continues execution. |
Execution gets stopped and job fails. Emails, notifications or following handlers configured in |
Success |
Job completes successfully. |
Job fails. Emails, notifications or following handlers configured in |
Error |
Job fails with the original exception. |
Job fails with the exception thrown from handler. Following handlers configured in |
The Mail and Notification handler supports a number of macros:
Macro | Supported on Event | Where |
---|---|---|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
All |
|
|
Error |
|
|
Error |
|
<Job>
...
<Events>
<Start>
<Notification>
<To>${JOB_INITIATOR}</To>
<Subject>TIF Part Basic job started</Subject>
<Message>The integration job started</Message>
</Notification>
</Start>
<Success>
<Notification>
<To>${JOB_INITIATOR}</To>
<Subject>TIF Part Basic finished successfully</Subject>
<Message>The job is now completed</Message>
</Notification>
<Handler className="com.acme.tif.CustomHandler" />
</Success>
<Error>
<Mail>
<To>${JOB_INITIATOR}</To>
<Subject>TIF Part Basic: Error</Subject>
<Message>Error encountered.
Message:
${ERROR_MESSAGE}
Stack trace:
${STACK_TRACE}
</Message>
</Mail>
<Notification>
<To>${JOB_INITIATOR}</To>
<Subject>TIF Part Basic: Error</Subject>
<Message>The integration job failed. The administrator has been notified.</Message>
<SystemTags>
<Tag key="origin" value="TIF" />
<Tag key="event" value="error" />
</SystemTags>
</Notification>
</Error>
</Events>
</Job>
In many places one can use macros that during runtime are resolved to real values. Depending on the context the possible macros varies, but in general, the table below illustrates the syntax of the macros and what they are resolved to.
Macro | Descriptions | ||
---|---|---|---|
|
Resolves the id of the current job |
||
|
Resolves the id of the current destination |
||
|
The ID of the TIF instance |
||
|
A setting from TIF named ABC |
||
|
A Java system parameter named AAA |
||
|
The ID of the ENOVIA user |
||
|
The ID of the source object in ENOVIA which the job relates to |
||
|
The TYPE of the source object in ENOVIA which the job relates to |
||
|
The NAME of the source object in ENOVIA which the job relates to |
||
|
The REVISION of the source object in ENOVIA which the job relates to |
||
|
The CURRENT STATE of the source object in ENOVIA which the job relates to |
||
|
CLASSNAME is a class implementing Example: ${job.java.a.b.c.TheResolver:the-key}
|
||
|
A custom select expression that is selected on the source object. Note that this results in extra DB calls. |
||
|
The ENOVIA RPE variable named ABC as set when the job was initiated Note that there is a legacy format available that does the same:
This format should however not be used since it will be removed in a future release. |
||
|
The parameter named ABC as specified when the job was initiated |