Message Watermarking & Verification

(Introduced in version 15)

Message watermarking is a feature which allows a queue device to verify the source of a message. Each message is watermarked by the originating Connexion or Remote Agent system, and then validated immediately before processing within the final Connexion (or Remote Agent) system. This is useful in ensuring that all messages received into a queue are expected - eliminating the possibility of accidentally branching or forwarding a message to the wrong destination. 

The watermarking feature piggy-backs off the message 'Sending Facility' field (typically MSH-4) which is persisted across forwards, branches, and remote agent send operations. For example, if we are ingesting messages from a specific customer via a remote agent, and forwarding these messages to a data-center hosted downstream system, we would watermark the message on the remote agent side, and then verify the watermark before forwarding the receiving system. Alternately, we can safeguard against sending data to the wrong customer's remote agent by verifying messages received from a datacenter-hosted Connexion.

The first step in enabling watermarking is to identify the first queue in the overall workflow. In this example, let's assume we're ingesting messages from a customer site via a remote agent. Navigate to the queue, select the 'Settings' tab followed by the 'Watermarking' tab.

In the 'Action' list, select 'Set Watermark'. This will automatically populate the watermark field (3) with a new random string. You can choose to use this random string or provide something with more meaning (such as a customer name or product id). This string will then be appended to the existing 'Sending Facility' property for each message received. In the example above, the existing sending facility is 'SHM' (from MSH-4) and therefore with watermarking enabled the sending facility will become SHM+C21145D0. In addition to providing your own 'tag' to append to the existing sending facility, you may also overwrite the existing sending facility by providing your own value (in field 2 above).

Notice that an icon is overlaid on the queue device icon (4) when watermarking is enabled.

If you inspect messages received by this queue with the watermarking feature enabled, you will see the 'tag' as part of the sending facility. Note that you may use the '*' wildcard character when filtering the queue in order query on specific original sending facilities (for example, 'SHM*').

Now that we have watermarked our messages in the source system, navigate to the last queue in the last channel of the workflow. In this case we are sending from a customer's remote agent into Connexion. With the last queue selected, choose the 'settings' tab, then 'watermarking' tab.

Set the 'Action' field to 'Verify Watermark'. In the 'Match List', enter a list of valid sending facilities (which you configured in the sending system). The default syntax is '+XXXXXXX' where the 'XXXXXXX' matches the tag you entered in the source system (field 3). The '+' character allows the matching of any string preceding the watermark tag. For example, '+C21145D0' will match 'SHM+C21145D0' and 'EPIC+C21145D0'. If you have left the sending facility field as default in the source system (field 2) then most likely you want to use the '+' option. If you have configured the sending facility in the source system or simply want to match on only one specific value, don't start your string with the '+' character. For example, 'SHM+C21145D0' is an exact match.

Note that a queue which is verifying a watermark will display the shield icon (3 in the image above).

Messages that fail a watermark test are moved to the error queue:

In some cases you may need to apply more advanced functionality when setting and/or verifying a watermark. Event hooks are provided where you can supply your own logic via a custom code device within the channel:

If you set the IsHandled property to true, the internal verification is bypassed in favor of your code. You may also throw an exception to fail validation and move the message to the error queue.