Real-Time Decisioning Rules Engine

Hidden Define your Real-Time Decisioning rules in the Rules Engine. A rule consists of IF <conditions> THEN <actions> logical operators. If the conditions are met, then the actions will be carried out. In an IF statement, one or more conditions can be concatenated with AND/OR/NOT logical operators. For example:

• Condition one: user_name contains John
• Condition two: checkout_time < 5 seconds

Rules are created by rules analysts on the Create Rule page.

​

About rules and rule sets

Rules form the foundation of the Real-Time Decisioning Decision Engine. Use rules to define the business logic that generates alerts, updates data sources, calculates features, triggers custom actions, and so on. Rules are organized into rule sets, which are invoked in decision flows.

​

Rules

​

Defining a rule

Use rules to evaluate a set of conditions and invoke one or more actions when those conditions are met. There are generally two types of rules:

• Rules that generate alerts: Also called detection rules.
• Rules that are used to perform non-alert actions: Non-alert actions include calculating a decision variable, updating a list, or calling another rule set.

When you create a new rule, you must define the following rule content sections:

• Rule name: The name of the rule. Rule names can contain spaces.
• Rule description: A meaningful description of the rule. You can use the AI Suggestion function to generate a description after you complete the rule definition.
• Tags: Use tags to add metadata to the rule.
• Score: Indicates the level of risk associated with a detection rule. When SML/UML models are used, the rule score is less relevant.
• Post processing rule: This option is deprecated and should not be used.
• Rule conditions: Specifies the conditions of the rule. Use the UI to create rules, and the Expression Builder to develop more complex conditions.
• Rule actions: Specifies the actions associated with the rule. Each rule can have zero or one primary action, and zero or many supplementary actions.

​

Defining conditions

A condition has three components:

• Features: Features are either derived from raw fields or generated by the Feature Platform. Multiple features can be concatenated with AND/OR/NOT logical operators.
• Constant Value: Specifies a sequence of elements.
• Operators: Specify how a feature can be processed. The available operators are dependent on the data type of the selected feature, visible on the left-hand side of the condition. You can combine individual conditions into compound conditions with AND/OR logical operators and condition blocks.

​

About features

You can select a feature from the dropdown list that includes raw features from your data, as well as derived features generated by Real-Time Decisioning’s Feature Platform. When you create a new feature in Feature Platform, it becomes available for you to use when creating rules. You can also click on Explore Features to view all available features. A modal window displays the details of each feature, including the Type, Description, and Creator. The following list describes the data types that Real-Time Decisioning can process:

• Boolean: Values of TRUE or FALSE.
• Numeric: Numeric data types include:
  • Integer: 32-bit positive, negative, or zero whole numbers that are not fractions. For example, 1 or 100.
  • Double: The 64-bit double-precision floating point data type that can represent both fractions and whole numbers, including zero. For example, 1.32, 323.2, 120.00, 120.
  • Long: Numbers up to 64 bits that are too large to be represented as an integer, including zero. For example, 9,223,372,036,854,775,807.
• String: String data types include:
  • Text: Strings represent text rather than numbers. Consists of a set of characters that can also contain spaces and numbers.
  • Normalized: Normalized strings of text. Fraudulent actors commonly use Unicode superscript or subscript to bypass rules that monitor for suspicious strings, such as Please textme directly to discussspecial prices. Real-Time Decisioning normalizes such a string to Please text me directly to discuss special prices, so that your rule will detect such fraudulent activities.

​

About operators

Operators are shown based on the selected feature’s data type. Select Explore Operators to view the range of available operators. The following table describes common operators for strings: The following table describes common operators for numbers:

​

Constant values

After selecting the feature and operator, the Rules Engine displays the Enter Value dialog box. For list operators, or operators that take a list as an input value, you can enter multiple values. After entering each value, press Enter. If the constant value is a single string, use the Highlight Spaces in Text button to check if you have accidentally entered spaces in the text. This is useful when copying text from other applications that include spaces.

​

Copying and deleting conditions

After adding a complete condition, you can copy it by clicking the Copy icon. Delete a condition by clicking the Trash icon.

​

Using regular expressions

Real-Time Decisioning supports regular expression (REGEX) input values. The following table defines the REGEX metacharacters: The following table describes REGEX character classes:

​

Defining rule actions

Real-Time Decisioning provides customized actions depending on your needs. If you need customized actions, contact your Marqeta representative. By default, the connecting logical operator between rule actions is AND, meaning that if you select two actions, both actions will be executed if the conditions are met. Real-Time Decisioning actions are system defaults that cannot be deleted. To add a new action, contact your Marqeta representative. The following table describes Real-Time Decisioning rule actions:

​

Testing rules

Feature Platform provides two ways to test your rules: Quick Test, and the testing capabilities in the Test Center. You can access the Test Center from the Rules Engine homepage. In the Test Center, you can perform three different types of tests: Basic Test, Comparison Test, or Simulation Test.

​

Quick Tests

You can run a Quick Test against a rule to quickly validate that the logic of the rule is correct. Use Quick Test to check the correctness of the rule logic of new or updated rules. To check if the rules will trigger correctly in the production system before publishing them, use the tools in Test Center. Test Center executes rules in a way that approximates how they are executed in the production environment. When running a Quick Test, you have three options for test data: you can use production data, use a dataset, or manually enter a JSON-formatted record.

​

Using production data in a Quick Test

You have two options when using production data for testing:

• Test against specific events by manually entering the event IDs. Choose this option when you know that the rule should be triggered by certain events.
• Specify the number of records in a time range. Choose this option when you want to see if any of the events in the time range trigger the rule. Using this option, you can also select test events from the latest events in the production system or select test events from a specific starting time when you noticed a new fraud pattern.

Select the optional Label feature to compare to the actual test result to quickly determine if the rule logic is correct. To reduce the size of the test dataset, use the Event Type filter to filter out any test records that do not apply. Event Type filters are applied to the total number of test records.

​

Using a dataset in a Quick Test

You can use a validated dataset when running a Quick Test on a rule. All feature calculations will be based on the test records in the dataset only. Select the optional Label feature to compare to the actual test result to quickly understand if the rule logic is correct. To reduce the size of the test dataset, use the Event Type filter to filter out any test records that do not apply. Event Type filters are applied to the total number of test records.

​

Manually entering a JSON-formatted record

You can manually enter a JSON-formatted record to test a rule in Quick Test. However, because JSON records do not support aggregation features, this test method is only useful when the rule you are testing does not use any aggregation features.

​

Debugging rules using Quick Test results

The test result panel displays the list of test records and whether they triggered the rule or not. The Conditions Met or Not column shows the computed value of each feature used in the rule, as well as if each condition segment is true or false. This information provides the detail needed to help understand why a rule triggered—or did not trigger—for each test record.

​

Using the Test Center

In the Test Center, you can perform three different types of tests:

• Basic Test: Use a Basic Test to validate individual rules or rule sets. Use this test to ensure that a newly created rule detects suspicious events or users as expected, or to verify if an existing rule is working as intended.
• Comparison Test: Use a Comparison Test to compare two rule sets to decide whether or not to retire one of them.
• Simulation Test: Use a Simulation Test to simulate the results of adding or removing Real-Time Decisioning rules.

​

Accessing the Test Center

To access the Test Center, click Test Center on the Real-Time Decisioning homepage. You can also access the Test Center while creating a rule. For your convenience, the latest test result for each test type is retained until a new test of that type is run.

​

Running a Basic Test

To run a Basic Test, click Basic Test on the Test Center page.

​

Selecting a rule or a rule set

You can choose to run a Basic Test on either a rule or a rule set. On the Basic Test page, click the Rule button or the RULESET button to select your test target. If you select RULESET, the test returns the result for all rules within the rule set. An additional table will be displayed to summarize the detection results of each rule.

​

Selecting a date range

Choose one of the four time range options: Custom, Last 1 day, Last 3 days, and Last 7 days. The Last X days options are calculated by hours, based on the last data point provided by your backend system. Last 7 days specifies a time span of 168 hours since the last detection time that Real-Time Decisioning received from your backend system. For example, if the latest data point event time is April 12, 13:50, and you select Last 1 day, Real-Time Decisioning will populate the data from 04/11/2024 13:50 to 04/12/2024 13:50.

​

Testing against manual input

Testing against manual input is an advanced option that allows you to verify if the condition logic of a rule or rule set is correct. To test against manual input, provide a row of data (such as a user or an event) in JSON format to test against a selected rule or rule set. Real-Time Decisioning treats JSON-formatted input as attribute-value pairs. The Rules Engine verifies the attribute-value pairs against the logic of the selected rules. If an attribute is mentioned as a feature in the rule condition but is not present in the manual input, Real-Time Decisioning treats it as if that condition is not met.

​

Reading the result table for a Basic Test

Detection Attributes are the features or attributes that are triggered in the rule conditions. For example, if Rule A has the conditions (IF Transaction > $4,000 OR Device Agent = "android 4.0"), then the detection attributes are Transaction and Device Agent. The triggered values of detection attributes are highlighted in the result table. For example, the value $5,000 would be highlighted because it is the value of the Transaction detection attribute that triggered Rule A. The result table also provides Export, Search, and Sort functions. If you need additional customized functions on the table, contact your Marqeta representative. Be aware that additional functions may result in a degradation in the performance of the result table.

​

Testing against a user identifier or an event identifier

You can evaluate whether the syntax of a rule or rule set is correct by testing it against specific users or events. You can choose whether the test will be performed at the user level or at the event level. In order to test for multiple users or events at one time, enter a comma-separated list of user or event identifiers. The result table displays the number of detected users or events on top, and specifies which users or events were detected by this rule or rule set.

​

Running a Comparison Test

To run a Comparison Test, click Comparison Test on the Test Center page.

​

Selecting a rule or a rule set

You can choose to run a Comparison Test on either a rule or a rule set. On the Comparison Test page, click the Rule button or the RULESET button to select your test target. If you select RULESET, the test returns the results for all rules within the rule set. An additional table will be displayed to summarize the detection results of each rule.

​

Selecting a date range

Choose one of the three time range options: Last 1 day, Last 3 days, and Last 7 days. The Last X days options are calculated by hours, based on the last data point provided by your backend system. Last 7 days specifies a time span of 168 hours since the last detection time that Real-Time Decisioning received from your backend system. For example, if the latest data point event time is April 12, 13:50, and you select Last 1 day, Real-Time Decisioning will populate the data from 04/11/2024 13:50 to 04/12/2024 13:50.

​

Reading the result table for a Comparison Test

In the Comparison Test result table, the net impact of Rule A is the number of unique detections found by Rule A only. The net impact of Rule B is the number of unique detections found by Rule B only. Meta-analytics provide an overview of detection results for Rule A and Rule B, including Total Detection, Unique Detection, and Overlapped Detection. You can filter the detection results in the result by those detected only by Rule A, only by Rule B, or by both Rule A and Rule B.

​

Running a Simulation Test

To run a Simulation Test, click Simulation Test on the Test Center page.

​

Selecting rules for simulation

By default, a Simulation Test includes all rules published at the time of the test. You can select which published rules you want to remove and which rules in trial or draft mode you want to add to the Simulation Test. The rules you selected for the Simulation Test are highlighted, and the count for how many rules are currently selected is updated in real time.

​

Reading the result table for a Simulation Test

The net impact of the simulated rules can be calculated by the following formula: Unique Detections by Simulation Rules - Unique Detections by Existing Published Rules. The resulting net impact can be negative if the simulated rules detect fewer unique results. The Result Table provides an overview of detection results for Total Detections, Unique Detections, and Overlapped Detections of the existing rules and the simulated rules within the same time range. By displaying the differences between the existing production rules and the simulated rules, you can study the impact of the simulated rules.

​

Managing rules

​

Analyzing rules

Real-Time Decisioning provides analytics data for each rule on its Rule Details page. To access the Rules Details page, click on any rule name displayed as a hyperlink from the Rules table on the homepage.

​

Rule metadata

Real-Time Decisioning provides three detection types: Total Detections, Unique Detections, and Overlapped Detections. A rule’s Unique Detections is the number of results (users or events) detected solely by that rule. A rule’s Overlapped Detections is the number of results detected by that rule, as well as one or more other rules. For example:

• Rule 1: Detected users {A, B, C, D, E}
• Rule 2: Detected users {A, E}

In this example, the Unique Detections count for Rule 1 is 3 because users {B, C, D} were detected by Rule 1 but not by Rule 2. The Unique Detections count for Rule 2 is 0 because Rule A also detected the users {A, E} that Rule 2 detected. Conversely, the Overlapping Detections count for Rule 1 is 2 because users {A, E} detected by Rule 1 were also detected by Rule 2. The Overlapping Detections for Rule 2 is 2 because users {A, E} detected by Rule 2 were also detected by Rule 1. The Total Detections count for Rule 1 is 5 because Rule 1 detected users {A, B, C, D, E}. The Total Detections count for Rule 2 is 2 because Rule 2 detected users {A, E}. In addition to detection results, you can view information in the Rules Details page such as Rule ID, Rule score, Created by, Created time, Last updated time, and Last updated by. If you have enabled the Queue Management function, the Rules Detail page also displays the queue with which the rule is associated.

​

Rule conditions

By default, the Performance Chart displays information from the last seven days of detection. However, you can adjust the display by selecting a different time range. When you select a new time range, the Performance Chart and the Result Table will both be updated.

​

Overlap Analysis

Overlap Analysis is a visual graph displaying which other rules have the most overlapping detection results with the currently selected rule. In the Overlap Analysis graph, Real-Time Decisioning displays only the top two rules that share the most overlapping detection results with the current rule. The Overlap Analysis graph displays data based on two time range options: the current day or the last seven days. Depending on the selected time range, the top two rules with the most overlapping detection results with the current rule may be different. The Result Table below the Overlap Analysis chart is dynamically displayed, based on which of the two time ranges is selected. Because the datasets from the current day and the last seven days are different, their respective detection results may differ.

​

Selecting users or events

If you have a mixed set of rules at both the user level and the event level, you can select which results to display. Your selection determines whether detected users or detected events are displayed in the Result Table of each Rules Details page, as well as in the various Result Tables of the Test Center page. For example, if you select Event, you will find that each detection row on the Rule Details page corresponds to an event beginning with an Event ID.

​

Exporting and importing rules

You can use the export function to export selected rules, scorecards, and decision flows. The selected entities are exported as a single JSON file, which can be then imported into another environment or tenant. This enables you to easily transfer rule entities between environments, such as between staging and production. When you import an exported file, the system will check if any entities with the same name already exist in the target environment. If such duplicate entities exist in the file, the system will automatically rename the imported entities. If you want to export and import all features and rule entities in a single action, you can use the Import/Export configuration function accessible in the Admin module. Use this function to export and import all detection strategy-related entities including data sources, features, and rules.