TIF ENOVIA/3DExperience Connector - RabbitMQ Message Receiver

1. RabbitMQ Listener / Message Receiver

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.

1.1. Configuration Details

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.

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.

1.1.1. XML Configuration Format

The root element is <AMQPListener>. The table below lists the allowed child elements

Element Required Description Example

Element	Required	Description	Example
`<Name>`	Yes	Defines a user friendly name of this configuration	`<Name>Part Queueue</Name>`
`<Destination>`	Yes	Defines what destination to listen from	`<Destination id="dest-xy"/>`
`<WithContext>`	No	Defines if to establish an ENOVIA/3DExperience context	`<WithContext user="Integration User"/>`
`<Handler>`	Yes	Defines the handler containing your business logic that is processing the message	`<Handler className="…" />` `<Handler type="…" />` `<Handler script="…" />`
`<Arguments>`	No	Some handlers might accept arguments.	`<Arguments> <Argument name="name-of-arg">value</Argument> <Argument name="another-arg" value="different format" /> </Arguments>`

<Name>

Yes

Defines a user friendly name of this configuration

<Name>Part Queueue</Name>

<Destination>

Yes

Defines what destination to listen from

<Destination id="dest-xy"/>

<WithContext>

Defines if to establish an ENOVIA/3DExperience context

<WithContext user="Integration User"/>

<Handler>

Yes

Defines the handler containing your business logic that is processing the message

<Handler className="…" /> <Handler type="…" /> <Handler script="…" />

<Arguments>

Some handlers might accept arguments.

<Arguments>
<Argument name="name-of-arg">value</Argument>
<Argument name="another-arg" value="different format" />
</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.

Attribute

Required

Description

user

If omitted, the super user will be used

securityContext

Defines the security context to be used

useDefaultSecurityContext

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

className: The name of a class implementing com.technia.tif.enovia.rabbitmq.MessageReceiver. See chapter below.
script: Name of a script resource. Example: script="tvc:script/MyMessageReceiver.js". See chapter below.
type: 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>

When TIF is running in development mode, you can edit, create or delete configurations at runtime and those will be hot deployed automatically without the need to restart the TIF instance or take any further action.

However, in production mode, you can only edit a definition at runtime, but in order to take the changes into use you need to restart the corresponding service activator from within the Administration UI. Add or delete configurations is not supported.

1.1.2. Registration via Module Properties

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/3DExperience context object should be allocated when the message receiver is invoked.	No. Default is false.
context.user	An optional name of a ENOVIA/3DExperience user (used if context = true). May be omitted to indicate that the default ENOVIA/3DExperience system-user should be used.	No. Defaults to the system user.
context.securityContext	Specify ENOVIA/3DExperience security context.	No
context.useDefaultSecurityContext	Specify to use the default security 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.

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/3DExperience context object should be allocated when the message receiver is invoked.

No. Default is false.

context.user

An optional name of a ENOVIA/3DExperience user (used if context = true). May be omitted to indicate that the default ENOVIA/3DExperience system-user should be used.

No. Defaults to the system user.

context.securityContext

Specify ENOVIA/3DExperience security context.

context.useDefaultSecurityContext

Specify to use the default security context on the user.

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.

1.2. Java Class

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: Do nothing
ACK: Acknowledges the current message
NACK: Rejects the current message
NACK_REQUEUE: Rejects the current message and requeues it
ACK_MULTIPLE: Acknowledges multiple messages, e.g. all messages that have not yet been ack/nack’ed
NACK_MULTIPLE: Rejects multiple messages.
NACK_MULTIPLE_REQUEUE: Rejects multiple messages and requeues all.

1.3. Script

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;
//}