TIF Administration and Configuration Guide - ENOVIA Connector

TIF has a routine for adding legacy data not yet being indexed, to the index by a Search Index Synchronizer.

There is a background task running on the TIF server that takes care about this.

This task is configured by default like this:

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.

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.

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.

To setup a new queue in ENOVIA, use the following MQL code as base for so.

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

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".

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.

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.

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.

Example

The example below will send the payload to:

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.

The <ExternalProcess> element allows the following content

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:

The <Exec> element defines what to execute and what arguments to supply to the external process.

This element supports the following attributes:

And the supported child elements are

The <Arguments> element allows nested <Arg> elements. Each occurence of such child element will result in an argument to be passed.

Other supported macros:

The currently supported post actions defined below <PostActions> are shown below:

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.

This element supports the following attributes:

And the supported child elements are

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:

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.

It is possible to store outbound payload that is visible in Admin UI. Use com.technia.tif.enovia.job.log.Logger.

For example:

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:

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:

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:

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:

In order for the client to know where the TIF server is located, you need to set some environment variables.

You can embed the invocation of a synchronous job in your own code by using the TIF classes like shown below:

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.

A configurable web-service is defined in an XML file that should be put inside the following folder:

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:

The final AAR files are stored internally under the following folder inside TIF:

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:

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

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:

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:

Below is a sample configuration illustrating some concepts.

The root element of this file must be <ExportServiceDefinition>.

The available child elements are listed in the table below.

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:

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:

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:

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:

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:

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:

or

For the other alternative, the possible child elements are shown in the table below:

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.

The possible child elements are shown in the table below:

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:

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:

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).

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:

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.

The root element of this file must be <UpdateServiceDefinition>.

The available child elements are listed in the table below.

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:

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.

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.

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:

Using the script attribute lets you define the update logic inside a script file instead. Below is an example of such:

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:

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:

Valid child elements are defined in the table below

If you have built a Webservice and packaged it as an AAR file, you can simply drop your AAR file with in the directory:

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:

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

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.

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.

You can set-up several directory listeners, each will then listen to different directories within the file-system.

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:

By default, auto registration is enabled and no resources are excluded.

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:

The first argument to the "handleEvent" is an enum instance, which may have the following values:

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:

or

or

A directory listener implemented as a script has the same method signature as the corresponding Java-class implementation.

The last argument is an object of type java.nio.file.Path

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:

By default, auto registration is enabled and no resources are excluded.

The Java class pointed out via the className attribute must implement the interface MessageReceiver in TIF. This API looks like:

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.

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:

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:

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:

By default, auto registration is enabled and no resources are excluded.

The Java class pointed out via the className attribute must implement the interface MessageReceiver in TIF. This API looks like:

The return value enum constants are described below.

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:

The script you write must implement "onMessage" and "onException" methods.

Example:

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:

By default, auto registration is enabled and no resources are excluded.

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:

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:

The script you write must implement at least the "onMessage" method.

Example:

The base URL for services are (by default):

A list of available services can be retrieved by accessing the base URL. Services are listed in JSON format. Example using cUrl:

Every service has a unique service name which is used when accessing it. For example, a service with the name part is available on:

Any information after the service name in the URL is interpreted as PathParameters. Example of URL using PathParameters:

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.

As an alternative you could also change the path for all applications by using the below example.

The %2$s refers to the name of the webapp folder.

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.

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.

The <Credentials> element contains the following attributes:

Valid child elements are defined in the table below