8 Message Transform, Filtering and Routing (TAFR)

After initial publication, a message may require a series of transformation, filtering, or routing operations. The RIB component that implements these operations is known as a Transformation and Address Filter/Router (TAFR) component.

A transformation operation changes the message data or contents.
A filter operation examines the message contents and makes a determination as to whether the message is appropriate to the specific subscriber.
A router operation examines the message contents and forwards the message to a subset of its subscribers. A filter operation can be considered a special case of a routing operation. Although logically separate operations, for performance reasons, TAFR components usually combine as many as is appropriate.

A TAFR's operation is specific to a message family and the set of subscribers to it. Multiple TAFRs may process a single message for a specific subscriber and different specific TAFRs may be present for different subscribers. Different sets of TAFRs are necessary for different message families.

Multiple TAFRs may be needed, depending on the types of subscribers. The following diagram shows the message flow with TAFR.

Surrounding text describes tafr_msgs.png.

TAFR Adapter Process

A Transformation Address Filter/Router (TAFR) adapter is used to perform operations on all messages from a single message family. The specific activities performed are dependent on the needs of its subscribers.

TAFRs in a message flow are an exception rather than a norm. (For example, a TAFR that does message transformation for only a single application is NOT encouraged or recommended going forward.) The subscribing application is responsible for filtering and transformation of the payload data.
Payload content based routing is not recommended as it degrades performance.
TAFR adapters take advantage of the RIB hospital.
Error messages are automatically retried by the hospital retry adapter.
The TAFR configuration makes most of the routing decision dynamic without requiring any configuration.
TAFRs are standard Java EE Message Driven Beans(MDB).
Custom TAFR business implementation can be easily plugged in by editing rib-tafr-adapters.xml.

Configuration

Deployment configuration of the TAFR in the javaEE container is handled by the rib-app-builder application. Refer the documentation for the rib-app-builder on how to deploy a TAFR application. The following is an example configuration in rib-tafr-adapters.xml.

<tafrs>
    <message-driven id="Alloc_tafr_1" initialState="running"
tafr-business-impl="com.retek.rib.domain.tafr.bo.impl.AllocToStockOrderFromRibBOImpl" />
</tafrs>

message-driven - Indicates that the TAFR is deployed as an MDB.
id - Indicates the id for this particular adaptor.
InitialState - Indicates the state of the adaptor.
Tafr-business-impl - Indicates the implementation class for this TAFR. This class contains the implementation for transformation, filtering and routing of RIBMessage.

Transformation

Message transformation is the process of converting one message family payload to another message family payload.

Filtering Configuration

Filtering configuration involves updating the rib-tafr.properties file with the appropriate information.

The property follows the usual properties naming convention (name=value).

The property that is used for filtering is "for.<tafr name>_tafr.drop-messages-of-types."

Example:

for.ItemsToItemsISO_tafr.drop-messages-of-types=
ISCDimCre,ISCDimMod,ISCDimDel,ItemImageCre,ItemImageMod,ItemImageDel,
ItemUdaDateCre,ItemUdaDateMod,ItemUdaDateDel,ItemUdaFfCre,ItemUdaFfMod,ItemUdaFfDel,
ItemUdaLovCre,ItemUdaLovMod,ItemUdaLovDel

This property should be read as "for ItemsToItemsISO tafr" drop these message types. A comma delimits the message types.

If customization is required then the rib-tafr.properties file needs to be updated for filtering to take place.

Routing

Routing is enabled by default for TAFR's, the RIB infrastructure handles this routing. If a TAFR requires routing based on message content, then implementation classes override the following method.

public void routeRibMessage(RibMessage newMsg,MessageRouterIface router) throws
 TafrException {    router.addMessageForTopic(eventType, newMsg);}

Configuration Example - Facility ID

One of the common configurations requirements is to set up the flow of transfers and orders to RWMS. This is based on Facility ID.

These examples and step-by-step instructions illustrate how to configure a TAFR for one and two RWMS deployments.

Single RWMS Configuration

RIB allows stock based transactions to be routed between different RWMS instances. An RWMS instance is assigned to a physical distribution center which may have one or more facilities assigned to it. A company may have one or more distribution centers.

By default the standard RIB configuration is set for a single RWMS instance. This means that all physical warehouses in RMS route directly to a single RWMS instance (in this case denoted as WH1) with each RMS physical warehouse directly correlating to a facility ID in RWMS.

Configuration Process

Modify the TAFR routing settings:
- For each physical warehouse set up in RMS there should be a matching entry in the rib-tafr.properties file. This file resides in the $RIB_HOME/application-assembly-home/rib-tafr directory and is used by the TAFR adapters, amongst other things, to route messages by facility ID to the correct RWMS instances.
- The file by default contains the following mappings:
  - facility_id.PROD.1=1
  - facility_id.PROD.2=1
  - facility_id.PROD.3=1
- The routing properties are structured in the following way: facility_id.<FACILITY_TYPE>.<RMS_PHYSICAL_WH_ID>=<RWMS_INSTANCE_NAME>
  - <FACILITY_TYPE> - This should match the facility_type.default value in the rib-tafr.properties file, in most cases this would be left as the default value which is "PROD".
  - <RMS_PHYSICAL_WH_ID> - The physical warehouse ID from RMS.
  - <RWMS_INSTANCE_NAME> - The RWMS installation topic name identifier that the warehouses messages will be routed to.
- These mappings must be edited so that each physical warehouse in RMS has its own entry. The physical warehouses can be found by running the following query in the RMS schema:
  - SELECT wh FROM wh WHERE wh.wh = wh.physical_wh;
- For the example in the diagram above, physical warehouse IDs 60, 70 and 80 would be returned by the query.
- There is only one RWMS instance (WH1) in this example and the RWMS installation topic name identifier is simply "1". This corresponds to the name of the topics that the RIB routes the messages to. This is also the default name suffix of the RWMS topics in the rib-integration-flows.xml file.
- Therefore, our mapping in the rib-tafr.properties file should read:
  - facility_id.PROD.60=1
  - facility_id.PROD.70=1
  - facility_id.PROD.80=1
Deploy the settings to the rib-tafr instance:
- The new TAFR routing settings need to be migrated to the rib-tafr instance. To do this run the following script found in the $RIB_HOME/deployment-home/bin directory.
  - rib-app-deployer.sh -deploy-rib-app-ear rib-tafr
Configuration should now be complete.

Note:
For every new physical warehouse added to RMS, the rib-tafr.properties file requires a new entry and the new settings need to be deployed to the instance.

Two RWMS Configuration

Surrounding text describes jms_provider.png.

Description

RIB can be configured to route stock based transactions between multiple distribution centers, each with their own RWMS instance. The purpose of this is to only send stock transactions that will be shipped to or from a certain warehouse to the distribution center that contains that warehouse (facility).

From RMS the user only has visibility to the warehouse that they are performing a stock shipment to or from, the RIB TAFR's then route the messages to the separate RWMS instances based on the configuration stated in the "rib-tafr.properties" file. In the above example, RMS physical warehouses 60 and 70 are assigned to the RWMS instance called WH1 while RMS physical warehouse 80 is assigned to another RWMS instance called WH2.

Configuration Process

Modify the TAFR routing settings:
- For each physical warehouse set up in RMS there should be a matching entry in the rib-tafr.properties file. This file resides in the $RIB_HOME/application-assembly-home/rib-tafr directory and is used by the TAFR adapters, amongst other things, to route messages by facility ID to the correct RWMS instances.
- The file by default contains the following mappings:
  - facility_id.PROD.1=1
  - facility_id.PROD.2=1
  - facility_id.PROD.3=1
- The routing properties are structured in the following way: facility_id.<FACILITY_TYPE>.<RMS_PHYSICAL_WH_ID>=<RWMS_INSTANCE_NAME>
  - <FACILITY_TYPE> - This should match the facility_type.default value in the rib-tafr.properties file, in most cases this would be "PROD".
  - <RMS_PHYSICAL_WH_ID> - The physical warehouse ID from RMS.
  - <RWMS_INSTANCE_NAME> - The RWMS installation topic name identifier that the warehouses messages are routed to.
- These mappings must be edited so that each physical warehouse in RMS has its own entry. The physical warehouses can be found by running the following query in the RMS schema:
  - SELECT wh FROM wh WHERE wh.wh = wh.physical_wh;
- Before editing the file for multiple RWMS instance routing, the user should know which RMS physical warehouses are to be routed to the particular RWMS instances and the RWMS installation topic name identifiers.
- For the example in the diagram above physical warehouse IDs 60 and 70 are routed to RWMS instance WH1 where the RWMS installation topic name identifier is "1" and RMS physical warehouse ID 80 are routed to RWMS instance WH2 where the RWMS installation topic name identifier is "2". To support this the mapping in the rib-tafr.properties file should read:
  - facility_id.PROD.60=1
  - facility_id.PROD.70=1
  - facility_id.PROD.80=2
Modify the rib-integration-flows.xml file:
- The RIB requires information on how to route the messages between the two RWMS instances. This is done by adding new entries to the rib-integration-flows.xml file.
- By default the file contains entries for the RWMS instance "rib-rwms" and all appropriate warehouse based adaptor mappings point to the et<TOPIC_NAME>WH1 topics. When adding multiple RWMS instances all the entries for RWMS need to be duplicated for the second instance "rib-rwms2" and all adapter mappings for the new instance need to point to et<TOPIC_NAME>WH1 topics.
- The entire "RWMS PUBLISHERS" section in the integration-flows.xml file needs to be duplicated and all new entries need to be changed to the second RWMS instance name of "rib-rwms2" for example:
  - <node id="rib-rwms2.ASNIn_pub" app-name="rib-rwms2" adapter-class-def="ASNIn_pub" type="DbToJms"><in-db>default</in-db><out-topic>etASNIn</out-topic></node>
- Each RWMS adapter mapping in the file that follows the et<TOPIC_NAME>WH1 format needs to be duplicated as well but needs to point to et<TOPIC_NAME>WH2. With the original adapter mapping and the new adapter mapping to route to the second RWMS instance, for the Stock Order adapter, the entry should be similar to the following example:
  - <node id="rib-rwms.StockOrder_sub" app-name="rib-rwms" adapter-class-def="StockOrder_sub" type="JmsToDb"><in-topic>etStkOrdersFromRIBToWH1</in-topic><out-db>default</out-db></node>
  - <node id="rib-rwms2.StockOrder_sub" app-name="rib-rwms2" adapter-class-def="StockOrder_sub" type="JmsToDb"><in-topic>etStkOrdersFromRIBToWH2</in-topic><out-db>default</out-db></node>
- The rib-integration-flows.xml file can be edited and then deployed in the following way:
  - cd $RIB_HOME/application-assembly-home/rib-func-artifacts
  - jar -xvf rib-func-artifact.war
  - cd integration
  - vi rib-integration-flows.xml
  - Make the changes specified above.
  - jar -uvf rib-func-artifact.war integration/rib-integration-flows.xml
Deploy the settings to the rib-tafr instance:
- The new TAFR routing settings need to be migrated to the rib-tafr instance, to do this run the following script found in the $RIB_HOME/deployment-home/bin directory.
  - rib-app-deployer.sh -deploy-rib-app-ear rib-tafr
Deploy the settings to the functional artifact:
- The new integration flow settings need to be migrated to the rib-func-artifact instance, to do this run the following script found in the $RIB_HOME/deployment-home/bin directory.
  - rib-app-deployer.sh -deploy-rib-func-artifact-war
Configuration should now be complete.

Note:
For every new physical warehouse added to RMS the rib-tafr.properties will require a new entry and the new settings will need to be deployed to the instance.

Note:
Multiple RWMS instances can be added as per the instructions above.

Changes to this configuration affect the following TAFRS.
- AllocToStockOrder
- ASNOutToASNInLoc
- CustOrderToStockOrder
- ItemLocToItemLocLoc
- OrderToOrderWH
- PendReturnToPendReturnWH
- RTVReqToRTVReqLoc
- TransfersToStockOrder
- WOInToWOInWH
- WOOutToWOOutWH