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:
- Data Elements (See What Are Data Elements)
- Rule Tags (See What Are Rule Tags)
- Operators (See Understanding the Types of Operators Used by the Rule Builder)
- Multi-Byte characters and encrypted parameters (See What Are Multi-Byte Characters and Encrypted Parameters)
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 ElementsEnable you to create a rule to identify suspicious transaction patterns on all channels.
- Device ElementsEnable you to create a rule to identify risk associated with a particular device.
- Geolocation ElementsEnable you to create a rule to analyze the user’s geolocation data from where the transaction was performed.
- Model ElementsEnable you to create a rule to analyze a transaction based on the Model score.
- Custom ElementsEnable 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.
- TransactionInformation: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 LocationsThe 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:
- 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.
- Extracts the parameter value (500) for the rule, and store it in a variable, say ParameterAmount.
- 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:
- Ensure that you are logged in as a GA or an OA.
- Activate theOrganizationstab.
- Click theSearchbutton on the page to display the list of organizations.
- UnderSelect Organizations to Modify, click the link with the organization’s name for which you want to delete the rule.
- Click theRisk Enginetab.
- Under theRules Managementsection on the side-bar menu, click theRules and Scoring Managementlink.The Rules and Scoring Management page appears.
- From theSelect a Rulesetlist, select the ruleset for which this configuration is applicable.The configuration information for the specified ruleset appears.
- ClickAdd a New Rule.The Risk Analytics Rule Builder page is displayed.
- 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.
- Select theChannelsandActionsfor which this rule is applicable.
- If you want to select all the channels and all the actions, select theAll ChannelsandAll Actionscheck boxes.Each rule must be associated with one or more Channels and Actions. By default, a rule is associated withAll ChannelsandAll Actions.
- Build the rule fragment, as follows:
- From theSelect Data Element(s)list, select from the following elements:
- Transaction
- Device
- Geolocation
- Model
- Custom
- Select the operator from theSelect Operatorlist to edit the rule that you are creating.
- ClickAddto add the rule fragment to theRule being developedarea.
- Build your complete rule by using the available logical operators, your rule fragment, and the rules in theSaved Ruleslist.
- ClickCreateto 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:
- Upload any data, if the rule uses a list.
- Enable the rule.
- Assign the ruleset (to which the rule belongs) to an organization.
- Migrate it to production.
- 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:
- In the Administration Console, access the Rules and Scoring Management page.
- From theSelect a Rulesetlist, select the ruleset for which this configuration is applicable.The configuration for the specified ruleset appears.
- Select theEnableoption against the rule you just created.
- ClickSaveat 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 canedit the rule definitionto fine-tune its performance.See section How to Edit Rule Definitions for more information.
- If the rule becomes obsolete, then you candelete the rule.See section How to Delete a Rule for more information.