Make decisions

The decision-making process is based on the rule engine that relies on two distinct rule files written in the Drools MVEL dialect:

• Default rule file is an out-of-the-box set of rules that should not be modified. These rules are designed to handle standard decision-making scenarios and serve as the baseline for the system. The file is located in S3: doc-upload/payment_sanctions_screening/{tara_version}/rules/rules_v1.drl.

• Custom rule file allows the implementation of specific rules tailored to business requirements. These rules are flexible and are used instead of the default ones, providing a way to handle a unique set of requirements. You can copy the default rule file, modify its content as needed, assign any name to your custom file, and add the name to the configuration. The file must be manually created and uploaded to S3: doc-upload/payment_sanctions_screening/rules/custom_rules.drl.

info

Do not change the filenames.

In the default rule file, if no rules fired, the default model decision is displayed:

"modelDecision: {
  "suggestedAction": "NO_DECISION",
  "comment": ""Cannot resolve potential match on sanctioned name(John Doe)
}

Create rule

Facts and globals

In Drools, globals and facts are two fundamental concepts used to pass external data and context to rules and represent the data that rules act upon:

• Facts are the data objects or domain objects that rules use to make decisions. A fact can be any Java object, and it serves as the basis for rule conditions, such as the when section of a rule. The following facts are defined:

  • PaymentMessage

  • PaymentMessageHit

  • PaymentInputEntity

  • PaymentDerivedData

  • PaymentWatchListEntity

  • TypeMatch

• Globals are external objects made available to your rules, but, unlike facts, they are not part of the working memory. Globals provide a way to inject external resources, services, or configuration settings into your rules. Globals are typically immutable within a single rule execution. Once set, the value does not change during the rule execution. The following globals are defined:

  • idMatch

  • typeMatch

  • nameMatch

  • countryMatch

  • addressMatch

  • nameMatchingThreshold

  • dateMatchingThreshold

  • modelDecision

By combining facts and globals, you can build complex and flexible rule-based systems that leverage external resources while making decisions based on the current state of your data.

See the example to illustrate the use of facts and globals in Drools:

import com.example.Order

global com.example.ShippingService shippingService

rule "Apply Shipping Discount"
when
    $order: Order(totalAmount > 100)
then
    double discount = shippingService.calculateDiscount($order);
    $order.applyDiscount(discount);
end

In the example:

• Order is a fact that represents the order with a total amount.

• shippingService is a global that provides access to a shipping service to calculate discounts.

• The rule applies a discount to the order if its total amount is larger than 100. It uses both the fact and the global to make this decision.

Additional functions

In the rule file, you can use the functions defined in the RulesUtil class:

• resolve("comment", rulesDecision) makes the RESOLVE decision.

• escalate("comment", rulesDecision) makes the NO_DECISION decision.

• minimumDistance(String date1, String date2) calculates the period between two dates.

• mapContainsValue(Map<String, String> messageMap, String key, String value) checks if a map key contains a given value.

• textContainsMapValue(String text, Map<String, String> valueMap) checks if the text contains a map value.

• textContainsValue(String text, String value) checks if the text contains a value.

• isValidStr(String value).

• isValidMap(Map<String, String> valueMap).

• isWleLocationInText(String text, PaymentWatchListEntity wle) checks if any sanctioned location elements are found in the text; used when a sanctioned type is LOCATION.

• isWleLocationInText(String text, PaymentWatchListEntity wle, boolean searchName) checks if any sanctioned location elements (name, city, country) are found in the text. Set boolean searchName to false to exclude name search, which allows using this function for any entity type or searching the whole content for the matching location.

• isLocationAnyMatch(String scrCountry, String wleCountry). Country can contain multiple pipe-separated values, such as RU|GB.

• isNameInText(String text, String name, boolean tokensOnly) returns true if all name tokens are found in the text.

• isNamesInText(String text, List<String> names, boolean tokensOnly) returns true if any name in the list or all name tokens are found in the text.

• String prepareConcatValue(String value) returns text in uppercase, without spaces and punctuation marks.

• String prepareValue(String value) returns text in uppercase, with trimmed spaces and without punctuation marks.

• hasMultipleTokens(String value) returns true if a string has multiple tokens separated by spaces or punctuation marks.

• hasNTokens(String value, int n) returns true if a string has more than N tokens separated by spaces or punctuation marks.

• int charsDifferenceDirectional(String one, String two) returns a minimum set of characters of String one that must be removed from (or added to) String two to make the strings equal.

• int charsDifference(String one, String two) returns a minimum set of characters that must be removed from (or added to) the respective strings to make the strings equal.

• isNameInclusive(String one, String two, boolean bidirectional) checks if one name token is contained within another. The boolean parameter controls if the name inclusion works both ways (true); otherwise (false), it returns true if the first name is contained within the second one.

• isHieroglyphsChars(String text) returns true if a string does not contain hieroglyphs.

• isLatinChars(String text) returns true if a string contains only Latin characters.

• transliterate(String text) transliterates a given string to Latin characters.

• textMatchRegex(String text, String regex, boolean fullMatch) matches or finds a regex pattern in a given text, with support for the Pattern.DOTALL, Pattern.CASE_INSENSITIVE, and Pattern.MULTILINE flags.

When

In most cases, the section is required to qualify a hit or watchlist entity for a new rule. You can use any objects mentioned above. See the code sample:

$hit: PaymentMessageHit(conditions via comma)
$wle: PaymentWatchListEntity(conditions via comma)
eval (expression)

Then

The section contains two available options:

• Resolve:

  resolve("comment", rulesDecision)

• Escalate:

  escalate("comment", rulesDecision)

Salience

The out-of-the-box default rules have salience in the range of 3000 to 1000.

In Drools, the salience attribute is a crucial element in the rule definition that influences the execution order of rules within a rule file. It allows you to specify the priority of a rule relative to the other ones. Rules with higher salience values are executed before rules with lower ones. You can assign an integer value to the salience attribute to set up the rule execution order.

Mind the following key points about the salience attribute in Drools:

• Execution order. The salience attribute determines the execution order of rules. The higher the value, the more important the rule is, and it gets executed earlier in the rule execution cycle.

• Default value. If a rule does not specify a salience value, it is assigned the default value of 0. Rules without explicit salience values are executed in an arbitrary order and can depend on the rule engine's internal decisions.

• Ascending order. When evaluating rules with the salience values, Drools arranges them in the ascending order. Rules with the lowest salience values are executed first, followed by rules with higher values.

• Negative values. You can assign negative salience values to rules if you want specific rules to be executed earlier than rules with positive salience values. For example, a rule with salience -1 is executed before a rule with salience 0.

• Use cases. The salience attribute is used to control the rule execution order or prioritize rules based on a specific business logic, for example, when specific rules should have precedence over others.

• Caution. While the salience attribute can be a powerful tool for rule prioritization, it should be used judiciously. Overusing or misusing of salience values can make rule sets complex and hard to manage. Maintain clarity in your rule definitions and document the reasons for setting particular salience values.

Thus, the salience attribute is a mechanism used to control the rule execution order based on assigned priorities. By assigning salience values to rules, you ensure that rules critical to your business logic execute in the desired order, allowing you to create a robust and efficient rule-based system.

Add custom rule file

To write rules, you can use the following applications:

• IntelliJ IDEA with the Drools plugin

• Eclipse with the Drools plugin (Business Rules Tools)

To add a rule, complete the following steps:

1. Create a custom rule file locally. The recommended filename is custom_rules.drl.

   You can use a different name for your custom rule file and specify it when configuring Tara. This allows you to maintain multiple versions of the rule file, which is useful for managing variations or retaining versions for auditing purposes.

2. Edit the rule file. Use any text editor of your choice to open the file.

3. Create a rule using the following template:

   rule "Name of the rule"
       activation-group "default"
       salience 2003
       when
           // Evaluation of the rule conditions goes here
       then
           // Define the actions to resolve or escalate based on the rule
   end

   1. Replace "Name of the rule" with a meaningful and descriptive name for your rule.

   2. Leave activation-group as "default".

   3. Set salience based on specific requirements.

   4. In the when section, define the conditions to be met for the rule to trigger.

   5. In the then section, specify the actions to be taken when the rule is triggered, including how to resolve or escalate the decision.

4. Save the changes.

5. Upload the modified file to S3: doc-upload/payment_sanctions_screening/rules/custom_rules.drl.

Example

As an example, let's implement the following business rule: "A hit should be resolved when the sender and the receiver are from the same country. Should be executed before the default rules."

1. Define the rule structure:

   • Leave activation-group "default". This is a required value.

   • Set salience to 4000. As the rule should be executed before the default one, you must set the salience value to more than 3000.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         
       then
         
   end

2. Define the when section:

   1. Specify the $message object.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         $message: PaymentMessage()  
       then  
   end
   2. Add base filtering for the message based on the payment info object.
   tip

   In Drools MVEL, you can call fields of the objects in () and also use . to access fields in the nested objects.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         $message: PaymentMessage(payment != null, payment.sender != null, payment.reciever != null)  
       then  
   end
   3. Add filtering for the country existing in the sender and receiver objects. Check for null values to avoid a Null Pointer Exception.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         $message: PaymentMessage(payment != null, payment.sender != null, payment.reciever != null, 
                   payment.sender.country != null, payment.reciever.country != null)  
       then  
   end
   4. Add a condition to evaluate the hit. You can use $message to get the sender and receiver data. Wrap all conditions in the eval() method to produce a Boolean outcome.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         $message: PaymentMessage(payment != null, payment.sender != null, payment.reciever != null, 
                   payment.sender.country != null, payment.reciever.country != null)
         eval($message.payment.sender.country == $message.payment.reciever.country)  
       then  
   end

3. Define the then section.

   rule "Sender and Receiver from the same country"
       activation-group "default"
       salience 4000
       when
         $message: PaymentMessage(payment != null, payment.sender != null, payment.reciever != null, 
                   payment.sender.country != null, payment.reciever.country != null)
         eval($message.payment.sender.country == $message.payment.reciever.country)  
       then
         resolve("Sender and Receiver countries are the same: " + $message.payment.sender.country, rulesDecision)  
   end

Migrate custom rules for version compatibility

The rule file structure can change between Tara versions, which might require manual synchronization with custom rules created in earlier versions. Mind the following:

• Check import statements and update them if needed.

• Update location match objects if applicable. For example, starting with Tara v3.3.0, the following changes are introduced:

  • LocationMatch is renamed to CountryMatch.
  • locationMatch is split into countryMatch and addressMatch.
  • global com.workfusion.sanctions.jnw.domain.rules.AddressMatch addressMatch; is added.

• If you set up filtering rules in previous Tara versions (up to Tara v3.3.0), transfer their settings to your custom rule file.

• The rule file can control which decision score to use per rule. Usually, all name match and mismatch rules use the Name Matcher score, and all type match and mismatch rules use the type confidence score. If you want control over this, replace one function with the other. Note that older versions of the functions below continue working as well:

  • RulesUtils.resolve("narrative", rulesDecision, typeMatch.inputTypeConfidenceScore);
  • RulesUtils.resolve("narrative", rulesDecision, nameMatch.score);
  • RulesUtils.escalate("narrative", rulesDecision, nameMatch.score);
  • RulesUtils.escalate("narrative", rulesDecision, typeMatch.inputTypeConfidenceScore);

• Add new import statements and a global variable declaration for the possible VESSEL type.

  import com.workfusion.sanctions.jnw.drools.CsvCacheHelper;
  import com.workfusion.sanctions.jnw.drools.CsvMatchCondition;
  
  global com.workfusion.sanctions.jnw.domain.rules.SecurityLookupData securityLookupData;

• Starting with Tara v3.4.0 and NER model v2.6.0, update the rules to account for the NER additional output possible_types field. It mainly affects type mismatch rules against the VESSEL sanctioned type. The change is optional; older files will continue to work as well.