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 automatic, suspect, and 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 automatic and suspect rule 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_FOUND conveys that two profiles named in the event have characteristics that suggest they are possibly related to one another. The other event, AUTO_LINK_FOUND is 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 suspect or automatic match group. Invent your name value for the type element, define a matchAction object with the same name as your rule type, and then map the handlers you wish within the matchAction object.

Type Value for the Custom Rule

You may invent any type value with no spaces, but you may not use the values automatic, suspect or 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 suspect or 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 third POTENTIAL_LINK_FOUND matchAction (bottom). She has invented the name 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 suspect or 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 type 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 PUBLISH_POTENTIAL_LINK_PAIR (not shown) and mapping the StreamingPotentialLinkActionHandler to it.

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 automatic rule uses.)

Available Handlers for the Match Action Object

The 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, POTENTIAL_LINK_FOUND)
  • StreamingAutoLinkActionHandler (publishes the event, AUTO_LINK_FOUND)

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 (POTENTIAL_LINK_FOUND, 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 relationship.

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.