Understanding Custom Rules
You can use the custom rule to define custom actions such as creating a relationship between two profiles instead of merging them.
Released in 2020.1, this capability extends the range of rule types beyond the
relevance_based types. With it you can define your own rule type
which can more granularly control the outcome than the other types. It also provides a
mechanism to link two profiles together with a relationship rather than merge them.
Specifically the custom rule can:
- Call the same action handlers that the
suspectrule types call but within the construct of this rule, it empowers you to package them into a broader set of calls if you wish.
- Publish an event type to a queue for the purpose of notifying an external program to
consider taking action on the event. Two event types to support this concept have
been provided. One called
POTENTIAL_LINK_FOUNDconveys that two profiles named in the event have characteristics that suggest they are possibly related to one another. The other event,
AUTO_LINK_FOUNDis just another type you can use to strongly suggest the two profiles are related to one another. Either can be published to the queue by your match rule. The intended objective is it allows your external program to receive the event, fetch the profiles, do further examination on them, and then if it agrees with the suggestion, POST an explicit relationship between the profile pair.
In order to use this rule type, you simply construct a match group as if you were creating a
automatic match group. Invent your name
value for the
type element, define a
object with the same name as your rule
type, and then map the handlers
you wish within the
Type Value for the Custom RuleYou may invent any
value with no spaces, but you may not use the values
relevance_based since they are already
used for the other three rule types.
Summary Architecture of Rule, matchAction, and Handlers
Refer to the example image below.
On the right you see a match group with the same construction as a traditional
automatic match group but the
type is of the user’s own invention.
On the left the user has architected three different match actions. Let’s review the
POTENTIAL_LINK_FOUND matchAction (bottom). She has invented
PUBLISH_AUTO_LINK_FOUND, which is also the name of the
rule type on the right which is no different in structure than a normal
automatic rule. If the rule formula
(and/exact/fuzzy,not) evaluates to TRUE, the
matchAction will get
called which in turn executes all of the handler classes it contains. In this case
there is only one, the StreamingAutoLinkActionHandler which publishes an event of
AUTO_LINK_FOUND to a queue. A program reacting to the event
can interpret this event type as a strong suggestion to POST a relationship between
the two entity IDs referenced in the event.
In the second
matchAction (middle) she has decided to publish the
other event type,
POTENTIAL_LINK_FOUND. She accomplished this by
inventing a custom rule type called
(not shown) and mapping the
In the first
matchAction (top) she has decided to call the
AutoMergeHandler which if executed will issue a directive to
merge the profiles (this is the same handler the
Available Handlers for the Match Action Object
matchAction object has four handler classes that can be called.
The first two are the legacy handlers used by the ‘automatic’ and ‘suspect’ types.
They are exposed for you to leverage if you wish. They are:
AutoMergeHandler(issues a directive to merge the profile pair)
SuspectMatchHandler(issues a directive to queue the profile pair for review, which means to make them available as potential matches in the Hub)
New with this rule type are two additional handlers that simply publish an event to the queue that was provisioned with your tenant. (You need not specify the queue URL, it is already known to your tenant.)
StreamingPotentialLinkActionHandler(publishes the event,
StreamingAutoLinkActionHandler(publishes the event,
Theory Behind the New Handlers
These new handlers were invented to support scenarios where it has been determined by
your match rule formula that two profiles should be linked to each other with a
relationship instead of being merged. Imagine scenarios such as a father and son,
manager and direct report, husband and wife, and so on. The reason for providing the
two event types (
AUTO_LINK_FOUND) is to allow you to leverage the comparison
logic available within a formula rule and simplify the logic you would have to write
in your event handler as regards the confidence level of the proposed
For example, you might construct one version of your rule that will detect a certain
kind of relationship (example, Father/Son) with very high confidence (suppose all
the attributes matched except for suffix which is Sr for one profile and Jr for the
other). The match action you would associate with that rule will be
AUTO_LINK_FOUND indicating to your external event handler to go
ahead and establish a relationship. Conversely you could have a slightly different
rule that detects the same relationship (Father/Son), but with low confidence (maybe
it doesn’t do a suffix comparison at all). In this case the match action you would
place into that rule will be
POTENTIAL_LINK_FOUND indicating to
your external event handler to queue this pair for review (or alternatively, you
could just use leverage the
SuspectMatchHandler). The choices are
up to you.