TIF ENOVIA/3DExperience Connector - Webspere MQ / Native MQ / IBM MQ Message Receiver

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.

Configuration Details

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.

XML Configuration Format

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

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>

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

className

The name of a class implementing com.technia.tif.enovia.nativemq.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: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>

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.

See also this chapter for more info

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.

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 mq 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/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.nativemq.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.

Java Class

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

    }
}

Script

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
}