TIF ENOVIA Connector - Inbound Integration Jobs

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

The access restriction can be defined based upon following:

The example below illustrates how you can construct the access restriction:

Or use an access program:

Or use an access expression:

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.

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.

The read operation supports generating content in XML or JSON format. The Accept header is used to determine which format to use.

To disable automatic payload transform based on the Accept header, set attribute autoTransform to false.

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.

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.

Client may also pass a list of filters by using multiple parameters.

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.

In addition, it should be configured with the following attributes how files are checked in.

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.

A request should be done with the "POST" method. Example:

The following attributes can be used on the <NewJob> element

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.

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

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.

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:

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 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:

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.

A reply handler is defined in an XML resource within the ${TIF_ROOT}/modules/enovia/cfg directory of type "replyhandler".

Example:

these configuration files are referenced as

A configuration defines the following aspects:

Lets look at the configuration format. Note that this is not a valid example it just illustrates all configuration aspects.

The <WithContext> element supports the following attributes.

Both the job-id locator and status-evaluator may be implemented in a few different ways:

The supported attributes on the JMS element are shown in the table below

For handling of replies from a JMS messaging systems the correlation id is used to correlate the message to its "source" in TIF.

By default, the message selector that is used for a JMS Source is set to

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.

The supported attributes on the RabbitMQ element are shown in the table below

Replies from a Rabbit MQ messaging system uses the correlation id of the message to correlate the message to its "source" in TIF.

By default, outgoing messages from TIF to RabbitMQ uses a correlation id that contains the following information

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.

The supported attributes on the NativeMQ element are shown in the table below

For handling of replies from a JMS messaging systems the correlation id is used to correlate the message to its "source" in TIF.

Example config for Native MQ source.

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.

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.

Moreover, we use a built-in status evaluator that has a very simple implementation:

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.

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:

Below is an example where two different reply handlers has been configured.

The most common configurations requires only the "config" property to be defined. However, there are additional properties available as shown below:

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:

The root element within a create/update configuration is <CreateConfiguration>, and this element supports the following attributes:

The allowed child elements are:

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.

The following input formats are supported:

Allowed child elements are:

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

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:

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:

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 allowed attributes on the <Config> element are:

The allowed child elements are:

The logic follows this flow:

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

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.

Below follows some examples how to construct an Identify Matching.

Example 1:

This would work on data that is structured like this

Example 2:

This would work on data that is structured like this

Example 3:

This would work on data that is structured like this

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.

Note that there are some common attributes shared by all child elements (except the CustomField).

Below are some examples how to construct a create value section.

Example 1:

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