Identifiers: message watermarking and audit tracking

The identifier feature(s) are subject to change based on user feedback

In 15R5 and previous versions of Connexion, the queue devices implemented a feature called ‘watermarking’. This concept allowed the creation and inclusion of a token with each message as it passed through the queue. At source systems, a token would be ‘stamped’ into the message object, and then the last queue in the workflow (often in a completely different system) would verify the token before forwarding the message on to a third party system.

This type of system is useful for ensuring that data doesn’t flow to wrong location or customer due to an accidental configuration error.

With the inclusion of auditing in R6, the watermarking feature has been removed from the queue device and replaced with “message identifiers”. Identifiers support an improved watermarking feature (verifying the source of the message stream), and are also included in audit records. On the auditing front, identifiers included with audit records let a human auditor easily determine which data (which customer, which facility) relates to a particular audit entry.

Identifiers are key/value string pairs (for example, key=“Customer Id”, value=”12345”). They are stored in a new specialized device call the “channel settings” device. The channel settings device is a non-processing container which sits at the start of a channel and stores the identity configuration. In order to use the identifier functionality, your channel must have a channel settings device.

The channel settings device currently only exposes two settings:

Set Identities: You wish to stamp each message passing through this channel with one or more key/value pairs. These values can optionally be verified by further down the workflow (often in a different Connexion or remote agent). The values here will also be included in any audit records created by messages flowing through this channel.

To enable setting identities, check the ‘set identities’ checkbox. Then, click the [+] icon in the ‘Identity Name’ column:

Edit the name and value as required.

These key/value pairs will be stored with each message queued to this channel. These values appear in the queue UI in the ‘identities’ column.

Note that you may use global notation to include global values in the ‘identity value’ column ({System.VarName}, {Group.VarName}, {Tab.VarName}).

In order to verify identities which have been set by an upstream channel, add a channel settings device to your channel and enable the ‘verify identities’ checkbox.

Use the [+] icon in the ‘Identity Name’ column and enter the name of the identity you’re expecting. Enter one or more values that you will accept for the given identity (separated by a comma).

If the message being queued into the channel does not contain the required identity name, or, the provided identity value does not match what has been configured, an exception is thrown. Depending on how the message arrived in the channel, the message may be returned to the sender as errored (remote agent sender, secure sender), or, queue into the channel in an errored state (branched into the channel).

Note that if you have both ‘set identity’ and ‘verify identity’ enabled on the same channel, and, the same identity name is configured in both, your verify settings must include the value(s) you’re setting in the ‘set identities section’.

Some organizations want to ensure that all channels within certain groups or tabs always have an identity set (ie, it is an error for a channel to not have set identities enabled). This is primarily for audit record completeness. We have added some experimental “nag” elements to the UI to indicate when a channel appears to be missing this configuration.

If you set the validation mode in the ‘Manage Tabs’ dialog or the Groups screen to ‘Must Validate Identifiers’, when a channel is requested to start, a check for an channel settings device with ‘set identifiers’ enabled and a key of ‘Enterprise Id’ is done. If this condition is not found, an orange nag bar is displayed.

Please note that many of these features are subject to change with feedback

Message identifiers are exposed programmatically via the context.MessageExtension property.

using System;
using System.Linq;
using System.Text;
using System.IO;
using System.Collections.Generic;
using System.Threading;
using Connexion.Core;
using Connexion.Core.HL7;
using System.Threading.Tasks;

namespace Connexion.Device
{
  public partial class CustomDevice : BaseCustomDevice
  {	
    public override async Task ProcessMessageAsync(IMessageContext context, CancellationToken token)
    {
      // add an identifier
      context.MessageExtension.AddIdentifier("key", "value");
      
      // add multiple identifiers
      context.MessageExtension.AddIdentifiers(new List<Identifier>() { new Identifier("key1", "value1"), new Identifier("key2", "value2") });
      
      // consume/check identifiers
      foreach(var identifierKvp in context.MessageExtension.Identifiers)
      {
        var key = identifierKvp.Key;  // the key of the identifier
        var identifier = identifierKvp.Value; // the identifier object associated with the above key
        var acceptedValues = identifier.Value;  // comma-delimited string of values
      }
    } 
  }
}