Creating Custom Rules by Using Rule Builder

The out-of-the-box rules in RA are generic and are configured for evaluating risk based on the rules that are applicable to all. If you need custom or industry-specific rules that are significantly different from those that RA provides out-of-the-box, then you need to deploy your own rules. RA provides a powerful feature called Rule Builder for this purpose. This feature is available through the Administration Console and is a GUI-based console that enables you to build rules on-the-fly by inputting information in various fields and controls.
cara
The out-of-the-box rules in RA are generic and are configured for evaluating risk based on the rules that are applicable to all. If you need custom or industry-specific rules that are significantly different from those that RA provides out-of-the-box, then you need to deploy your own rules. RA provides a powerful feature called
Rule Builder
for this purpose. This feature is available through the Administration Console and is a GUI-based console that enables you to build rules on-the-fly by inputting information in various fields and controls.
The information that you need to supply to this Rule Builder includes:
Examples of Using New Rules illustrates with examples how these rule building blocks can be used.
How to Create a Custom Rule and After Creating a Custom Rule, What Next walk you through the process of creating a new rule and ensuring that it is used in future risk evaluations by RA. Finally, What Else Can I Do with My Custom Rule discusses how to manage the your custom rule..
What are Data Elements
You can select from the following types of data elements to build a new rule using Rule Builder:
  • Transaction Elements
    Enable you to create a rule to identify suspicious transaction patterns on all channels.
  • Device Elements
    Enable you to create a rule to identify risk associated with a particular device.
  • Geolocation Elements
    Enable you to create a rule to analyze the user’s geolocation data from where the transaction was performed.
  • Model Elements
    Enable you to create a rule to analyze a transaction based on the Model score.
  • Custom Elements
    Enable you to create your own data element, which is not available in the list of pre-configured data elements.
Note:
For detailed information on Data Elements that can be used in each channel and the the operators that are allowed with them, see Understanding Data Elements.
What are Rule Tags
Rules take data elements, called
tags
, as input. In other words, data elements are also known as Tags in RA terinology. Two most common tags used by RA are the end user's country and the transaction amount. These tags are then referenced in rules either through an explicit reference called a
TagName
, or by using an implicit reference by the context of the rule.
You can use the data listed in the following table to include in your rules. This data is classified into the following broad categories:
  • User Information:
    Provides information about the user and the account.
  • Device Information:
    Provides information about the device used to originate the transaction.
  • Transaction
    Information:
    Provides information about elements of every transaction, such as the channel and action.
  • Currency Information:
    Provides information such as currency conversion rate and base currency.
  • Location Information:
    These elements are derived from a maintained database of IP geolocation, which provides location data and connection attributes of the IP address.
  • Internal Parameters:
    Support the construction of custom rule types.
Note:
Some of this data is collected by the
evaluateRisk()
API call with the help of extensible data structures called
contexts
. On the other hand, the other data is derived through lookups, such as the geolocation of the end user's or cardholder's IP address.
Tag Name
Channel
Description
User Information
IDENTITY.USERID
All
The user identifier. If encryption was enabled, then this tag represents the encrypted version of the user identifier.
RULESET.GROUPNAME
All
The organization name.
Device Information
DEVICEID.http
Default, 3D Secure
The alpha-numeric ID assigned by RA for this device.
DEVICEID.flash
Default, 3D Secure
The Flash device ID string specific to the transaction.
DEVICESIG
Default, 3D Secure
The device signature gathered from the end user’s system to generate a risk profile of a device in real time.
SHORTDEVICESIG
Default, 3D Secure
The compact form of the device signature.
AGGREGATORINFO
Default, 3D Secure
Aggregator ID string specific to the transaction.
RULE.SIGPASSTHRESHOLD
Default, 3D Secure
Pass threshold used by the Device MFP Match rule.
General Transaction Information
RULESET.CHANNELNAME
All
The channel using which the user accesses the system.
TRANSACTION.TXNID
All
The numeric identifier for this transaction generated by RA.
TRANSACTION.EXT
Default, 3D Secure
Name-value Extensible element string sent by the client.
Currency Information
BASE_CURR_CODE
3D Secure, ATM, POS
Numeric designation corresponding to the 3-letter designation of the base currency of the organization.
BASE_CURR_AMOUNT
3D Secure, ATM, POS
Transaction amount converted to the Base Currency.
BASE_CONVERSION_RATE
3D Secure, ATM, POS
Conversion rate from transaction currency to the base currency of the organization.
Location Information
RULESET.COUNTRYISO
Default, 3D Secure
Contains the two letter ISO 3166 alpha country code of the country, for example AU.
RULESET.STARTIP
Default, 3D Secure
Starting IP for the user IP block.
RULESET.ENDIP
Default, 3D Secure
Ending IP for the user IP block.
RULESET.GEOLAT
Default, 3D Secure
Latitude is expressed as a floating point number with positive numbers representing North and negative numbers representing South.
RULESET.GEOLONG
Default, 3D Secure
Longitude is expressed as a floating point number with positive numbers representing East and negative numbers representing West.
RULESET.GEOCF
Default, 3D Secure
Confidence Factor (CF) in the geolocation.
Confidence Factors are calculated based on the precision, completeness, and consistency of the data available to assign a specific geographic location to an IP address range.
Confidence Factors are provided for Country, State, and City. Their value ranges from 1 to 99. A higher value indicates that the likelihood of a correct location assignment is higher; a lower value indicates the opposite. These values are not percentages. Their intended use is as a relative measure of "confidence" on the correctness of the corresponding location assignment.
Internal Parameters
RULE.USERCONTEXT
Default, 3D Secure
User context information used internally by the rules engine to store state information.
RULE.DEVICECONTEXT
Default, 3D Secure
Device context information used internally by the rules engine to store state information.
ADDONRULE.DESCRRESULT
All
The concatenated string of results from the add-on rules called till this point.
ADDONRULE.ANNOTATION
All
The concatenated strings of annotations set by all add-on rules called till this point.
RULE.RULEMNEMONIC
All
Rule mnemonic configured for the rule.
 
The following table provides an interpretation of RESULT_DEVICEIDCHECK.
RESULT_DEVICEIDCHECK
DEVICEIDCHECKRULE
USERDEVICEASSOCIATEDRULE
ISDEVICEKNOWN
ISUSERASSOCIATED
YY
Enabled
Enabled
Y
Y
NN
Enabled
Enabled
N
N
YN
Enabled
Enabled
Y
N
<blank>
Enabled
Disabled
Y
None
NN
Enabled
Disabled
N
None
<blank>
Disabled
Disabled
None
None
 
What are Operators
See Understanding the Types of Operators Used by the Rule Builder for details on operators that you can use with data elements to create complex equations.
What are Multi-Byte Character and Encrypted Parameters
RA supports the UTF-8 standard, which is a variable-width 8-bit encoding format of the universal Unicode encoding scheme. This variable-width encoding enables you to use varying number of bytes to encode a character set.
For information about configuring UTF-8, see the Installing section.
RA also enables you to use hardware- or software-based encryption of your sensitive data. You can choose to encrypt sensitive parameters and also decide whether you want to display clear text data or encrypted data in Reports. The following table lists the parameters that can be selected for encryption and multi-byte character encoding. It also lists the keys used for the parameter and the level at which the key is applicable.
Parameter
IsEncrypted
HSM Support
KeyLevel
Key Type
IsMultiByte
UserName
Optional
Yes
Organization
OrgKey
Yes
User attributes
Optional
Yes
Organization
OrgKey
Yes
Configurations
Action
No
No
None
None
No
OrgName
No
No
None
None
No
DeviceID
No
No
Global
Fixed - Internal
Yes
Device Signature
No
No
None
None
Yes
CALLERID
No
No
None
None
Yes
CONFIGNAME
No
No
None
None
No
CHANNELNAME
No
No
None
None
No
CLIENTIPADDRESS
No
No
None
None
No
AGGREGATORNAME
No
No
None
None
No
ASSOCIATIONNAME
No
No
None
None
No
ACCOUNTTYPE
No
No
None
None
No
MATCHEDRULE
No
No
None
None
No
LINESPEED
No
No
None
None
No
CONNECTIONTYPE
No
No
None
None
No
ANONYMIZERTYPE
No
No
None
None
No
IP_ROUTINGTYPE
No
No
None
None
No
Rule Mnemonic
No
No
None
None
No
Rule Name
No
No
None
None
Yes
Rule Description
No
No
None
None
Yes
ACCOUNTID
No
No
None
None
Yes
PARENTUSERID
No
No
None
None
Yes
ERROR MESSAGE
No
No
None
None
Yes
QUEUE NAME
No
No
None
None
No
QUEUE DESCRIPTION
No
No
None
None
Yes
CASENOTE
No
No
None
None
Yes
3D Secure Elements
ACQ_BIN
No
None
None
None
No
MERCHANT_NAME
No
No
None
None
Yes
MERCHANT_ID
No
No
None
None
No
MERCH_COUN
No
No
None
None
No
MERCHANT_URL
No
No
None
None
No
XID
No
No
None
None
No
PURCHASE_DESCRIPTION
No
No
None
None
Yes
PAN
No
No
None
None
No
EXPIRY
No
No
None
None
No
MERCH_CAT
No
No
None
None
No
TERM_URL
No
No
None
None
No
PREVTXNDATA
No
No
None
None
No
The following table describes whether the parameter is case-insensitive and whether it is displayed in reports.
Parameter
Case Insensitive
Displayed in Reports
UserName
Yes
Yes
User attributes
Yes
Yes
Configurations
Action
No
Yes
OrgName
No
Yes
DeviceID
No
Yes
Device Signature
No
No
CALLERID
No
No
CONFIGNAME
No
Yes
CHANNELNAME
No
Yes
CLIENTIPADDRESS
No
Yes
AGGREGATORNAME
No
Yes
ASSOCIATIONNAME
No
 
ACCOUNTTYPE
No
Yes
MATCHEDRULE
No
Yes
LINESPEED
No
 
CONNECTIONTYPE
No
 
ANONYMIZERTYPE
No
Yes
IP_ROUTINGTYPE
No
 
Rule Mnemonic
No
Yes
Rule Name
No
Yes
Rule Description
No
Yes
ACCOUNTID
No
Yes
ERROR MESSAGE
No
No
QUEUE NAME
No
Yes
QUEUE DESCRIPTION
No
Yes
CASENOTE
No
Yes
3D Secure elements
ACQ_BIN
No
Yes
MERCHANT_NAME
No
Yes
MERCHANT_ID
No
Yes
MERCH_COUN
No
Yes
MERCHANT_URL
No
Yes
XID
No
No
PURCHASE_DESCRIPTION
No
No
PAN
No
No
EXPIRY
No
No
MERCH_CAT
No
No
TERM_URL
No
No
PREVTXNDATA
No
No
Examples of Using New Rules
The following examples illustrate how you can combine out-of-the-box RA rules and your rules to define custom combination rules by using multiple factors and conditions:
  • High Amount Check
  • High User Velocity from Unexpected Locations
  • High Device Velocity from Unexpected Locations
  • Wire Transfers from Unexpected Locations
    The rule (for example, SAFE_COUNTRIES) that you see in these examples represent a simple list rule that uses a list of countries considered to be the origin of safe transfers.
  • Daily Maximum Amount Check
  • Transactions Exceeding Thresholds
  • Transactions Exceeding Thresholds for a Specified Action
 
High Amount Check
Consider the following details for an AMOUNT_CHECK rule that must check for transaction amounts more than $500:
Rule Mnemonic: HIGHAMTCHK Rule Display Name: High Amount Check Description: This rule checks for high transaction amounts that exceed $500. Amount: 500
This example rule performs the following:
  1. Parses the AdditionalInput string (say Amount=750) that is passed in the evaluateRisk() API call by the tag named Amount, and extract the value of this tag in a variable, say ActualAmount.
    Refer to the Javadocs for details on parsing the AdditionalInput elements.
  2. Extracts the parameter value (500) for the rule, and store it in a variable, say ParameterAmount.
  3. Returns Matched because ActualAmount(750), in this case, is greater than ParameterAmount (500).
 
High User Velocity from Unexpected Locations
Consider that the SAFE_COUNTRIES refers to a simple list rule (where some of the elements are US,CA, UK, DE), then you can define a new rule to determine transactions with high User Velocity from unusual locations as:
USERVELOCITY AND NOT SAFE_COUNTRIES
 
High Device Velocity from Unexpected Locations
Similar to "High User Velocity from Unexpected Locations", you can define a new rule to determine transactions with high Device Velocity from unusual locations as:
DEVICEVELOCITY AND NOT SAFE_COUNTRIES
 
Wire Transfers from Unexpected Locations
Consider that you have created a rule called HIGHAMTCHK (as discussed in "High Amount Check".) Also, if the SAFE_COUNTRIES rule uses a list of countries considered to be origin of safe transfers, then you can define a rule to track low-value or high-amount wire transfers from unusual locations as:
(HIGHAMTCHK OR Amount < 20) AND NOT SAFE_COUNTRIES
Daily Maximum Amount Check
If the card holder has withdrawn cash exceeding the set threshold for three consecutive days (including the day of the current transaction), then you can restrict the current transaction.
Channel: ATM Action: WITHDRAW Element: Amount Operator: GROUPED_CUMULATIVE_AMOUNT Operator Parameters: Threshold Cumulative Amount = <Desired Threshold Amount> Grouping Period Count = 3 Minimum Threshold Breach Count = 3 Duration to look back(in Minutes)= 4320 Maximum Transactions to look back = 100 Time Frame Start Time = 0000 Time Frame End Time = 2359 Transactions to Consider = ALL
Three period groups (1 Group = 1 calendar day) are created, including the group (day) for the current transaction. The rule is triggered if the Threshold Cumulative Amount is exceeded for all the three groups (days).
 
Transactions Exceeding Thresholds
If the card holder has used the card for an amount exceeding the set threshold in the last one day or performed more than the specified number of transactions in the last one day for specified types of transactions, such as specific merchant categories or specific countries, then you can restrict the current transaction.
Channel: POS Action: PURCHASE Element: Amount Operator: CUMULATIVE_AMOUNT Operator Parameters: Threshold Cumulative Amount = <Desired Threshold Amount> Threshold Transaction Count=10 Duration to look back(in Minutes)= 1440 Maximum Transactions to look back = 100 Transactions to Consider = ALL AND Element: MERCH_CAT Operator: IN_LIST
If the cumulative amount in the specified time frame (one day) exceeds the Threshold Cumulative Amount or the number of transactions exceeds the Threshold Transaction Count, then the rule is triggered.
 
Transactions Exceeding Thresholds for a Specified Action
If the card holder has changed their PIN in the last one day and has used the card for an amount exceeding the set threshold in the last one day or performed more than the specified number of transactions in the last one day for specified types of transactions, such as specific merchant categories or specific countries, then you can restrict the current transaction.
Channel:ATM Action:WITHDRAWAL Element:Amount Operator:ACTION_CUMULATIVE_AMOUNT Operator Parameters: Threshold Cumulative Amount = <Desired Threshold Amount> Threshold Transaction Count=10 Duration to look back(in Minutes)= 1440 Maximum Transactions to look back = 100 Threshold Action = PINCHANGE Transactions to consider = All AND Element:MERCH_CAT Operator:IN_LIST
If there was a PINCHANGE in the specified time frame (one day) and if the cumulative amount in the specified time frame (one day) exceeds the Threshold Cumulative Amount or the number of transactions exceeds the Threshold Transaction Count, then the rule is triggered.
How to Create a Custom Rule
To build a new rule to meet your business requirements:
  1. Ensure that you are logged in as a GA or an OA.
  2. Activate the
    Organizations
    tab.
  3. Click the
    Search
    button on the page to display the list of organizations.
  4. Under
    Select Organizations to Modify
    , click the link with the organization’s name for which you want to delete the rule.
  5. Click the
    Risk Engine
    tab.
  6. Under the
    Rules Management
    section on the side-bar menu, click the
    Rules and Scoring Management
    link.
    The Rules and Scoring Management page appears.
  7. From the
    Select a Ruleset
    list, select the ruleset for which this configuration is applicable.
    The configuration information for the specified ruleset appears.
  8. Click
    Add a New Rule
    .
    The Risk Analytics Rule Builder page is displayed.
  9. Enter the basic information for the rule, as described:
    • Name: The display name for the rule that you want to create.
    • Mnemonic: A short name for the rule that is used for logging purposes and in APIs. The maximum length of the mnemonic is 15 characters and no spaces are allowed.
    • Description: A short description of the rule being created.
  10. Select the
    Channels
    and
    Actions
    for which this rule is applicable.
  11. If you want to select all the channels and all the actions, select the
    All Channels
    and
    All Actions
    check boxes.
    Each rule must be associated with one or more Channels and Actions. By default, a rule is associated with
    All Channels
    and
    All Actions
    .
  12. Build the rule fragment, as follows:
    1. From the
      Select Data Element(s)
      list, select from the following elements:
      • Transaction
      • Device
      • Geolocation
      • Model
      • Custom
    2. Select the operator from the
      Select Operator
      list to edit the rule that you are creating.
    3. Click
      Add
      to add the rule fragment to the
      Rule being developed
      area.
  13. Build your complete rule by using the available logical operators, your rule fragment, and the rules in the
    Saved Rules
    list.
  14. Click
    Create
    to create your rule.
After Creating a Custom Rule, What Next
After you create a new rule, you need to do the following tasks so that the rule is used during risk evaluation:
  1. Upload any data, if the rule uses a list.
  2. Enable the rule.
  3. Assign the ruleset (to which the rule belongs) to an organization.
  4. Migrate it to production.
  5. Refresh the server cache.
The following steps quickly explain these tasks.
Step 1: Upload Rule List Data, If Any
If your rule uses a list of values against which it assesses a condition, then you need to upload that data as a list.
To upload the data for a list, see, How to Upload Rule List Data for detailed instructions.
 
Step 2: Enable the Rule
The rule that you just created (How to Create a Custom Rule) must be enabled so that it can be a part of the parent ruleset. To enable the rule:
  1. In the Administration Console, access the Rules and Scoring Management page.
  2. From the
    Select a Ruleset
    list, select the ruleset for which this configuration is applicable.
    The configuration for the specified ruleset appears.
  3. Select the
    Enable
    option against the rule you just created.
  4. Click
    Save
    at the bottom of the rules table.
 
Step 3: Assign the Ruleset to Which the Rule Belongs
After you activated the new rule by enabling it (as discussed in the preceding section), then the next thing you will need to do is activate the parent ruleset to which your rule belongs. This process of activating a ruleset is known as assigning a ruleset.
To assign a ruleset, see, How to Assign a Ruleset to an Organization for detailed instructions.
 
Step 4: Migrate the Rule to Production
When the rule is configured, it is still in the Proposed Configuration area and is only still available in the
Proposed
column of rule configuration. When the rule is ready and all its data is configured according to your requirements, then you must convert it from its current the Proposed state to Active state (the
Active
column on respective configuration page). This can only be done by migrating it to production.
To make the changes active, see How to Activate a Rule (Migrate Rules to Production) for detailed instructions.
 
Step 5: Refresh the Server Cache
Migrating a major change (such as a new rule) to production does not affect the cache of the active server instances. Each instance's cache needs to be refreshed before the server can start serving it for risk evaluations. That is why, you now need to refresh the server cache.
To refresh the cache of all deployed Transaction Server instances, see How to Refresh Server Cache for detailed instructions.
What Else Can I Do with My Custom Rule
After you have successfully created and activated a rule for risk evaluation, you can manage the rule as follows:
  • At a later stage, you can
    edit the rule definition
    to fine-tune its performance.
    See section How to Edit Rule Definitions for more information.
  • If the rule becomes obsolete, then you can
    delete the rule
    .
    See section How to Delete a Rule for more information.