Fraud language reference

Microsoft Dynamics 365 has its own rich and expressive language to help you define and express your fraud strategy. This language has many similarities to C# and SQL, and is designed to give you the flexibility that you need to address fraud for your unique business scenarios.

You can use this language today to define rules and velocities. For more information, see Manage rules and Perform velocity checks.

This fraud language reference guide includes the complete list of operators, functions, and statements that make up the language:

• Statements
• Referencing attributes and variables
• Defining your own variables
• Global Variables functions
• Decision functions
• Observation functions
• Aggregation functions
• Logical operators
• Comparison operators
• Math functions
• DateTime functions
• Type casting operators
• String functions
• Gibberish detection functions
• Pattern detection functions
• Model functions
• Geo functions
• Device attribute functions
• BIN Lookup functions
• List functions
• Using lists in rules
  • ContainsKey
  • Lookup
• Using external calls, external assessments and velocities
• Type inference of attributes
• JSON arrays and objects
• Functions available within Post Decision Actions

Statements

Referencing attributes and variables

You can use the at sign (@) operator to reference an attribute from the current event.

Defining your own variables

You can use the LET keyword to define a variable. That variable can then be referenced in other places in the rule. Prefix all variables by a dollar sign ($). For example, you declare the following variable.

LET $fullName = @"user.firstName" + @"user.lastName"

Variables that are declared in a LET statement can be used only within the scope of the rule or velocity set that the statement is defined in.

For example, to reference the variable from the previous example, you can write the following statement.

WHEN $fullName == "Kayla Goderich"

Global Variables functions

You can use Global Variables functions to set and get variables within rules. Once global variables are set, they can be accessed within a decision rule, velocity, routing rules, and post-decision actions within the same environment or children environments. The hierarchy Fraud Protection uses is listed in the following table. For example, if you set global variables in a rule within the root environment, Fraud Protection can retrieve its value within any other rule in the same assessment in the same environment, or any children environments.

Decision functions

Decision functions are used in rules to specify a decision.

Observation functions

Observation functions can be used to take data from the current context and write it somewhere else.

Aggregation functions

Logical operators

Comparison operators

Fraud Protection supports all standard C# comparison and equality operations. This table includes some examples of operators that you might find useful. If you apply these operators to strings, lexicographic comparisons occur.

Math functions

Fraud Protection supports all standard C# math methods and arithmetic operators. This table includes some examples of methods that you might find useful.

DateTime operators

Fraud Protection supports the standard C# DateTime properties, methods, and operators. This table includes some examples of functions and properties that you might find useful.

Type casting operators

For information about type inferencing, see the Type inference of attributes section later in this article.

String functions

Fraud Protection supports the standard C# string class. This table includes some examples of functions and operators that you might find useful.

Using CharSet in ContainsOnly, ContainsAll, and ContainsAny

The following character types can be used in ContainsOnly, ContainsAll, and ContainsAny.

Gibberish detection functions

These functions help prevent fraud by quickly and efficiently detecting whether key user-input fields (such as names and addresses) contain gibberish.

Pattern detection functions

These functions help prevent fraud by quickly and efficiently detecting whether key user-input fields (such as names and addresses) contain gibberish.

Model functions

Model functions run the various fraud models and are useful when your assessment doesn't automatically run one or more fraud models. When model functions run, information about the model running during rule evaluation is output in the fraud assessment API call. Then, the rule gets access to the model result, including score, reasons, and more, that can be used for further rule processing and decision making.

Geo functions

Geo functions provide resolution by converting an IP address to a geographical address. Geo functions can be invoked in rules only by using IPs that are part of transaction payload or collected by Fraud Protection by using Device Fingerprinting. Geo functions can't be invoked for arbitrary IP values.

Device attribute functions

BIN Lookup functions

BIN Lookup functions provide payment card account information (for example, card network, card type, card country code, card category) based on bank identification number (BIN). Data for BIN Lookup is sourced from leading third-party BIN data providers and then curated by Fraud Protection.

List functions

Fraud Protection lets you upload custom lists and reference them in the language. For information about how to upload these lists, see Manage lists. For more information about how to use lists in rules, see the Using lists in rules section later in this article.

Using lists in rules

You can use the ContainsKey and Lookup operators to reference lists that you uploaded to Fraud Protection. For more information about lists, see Manage lists.

ContainsKey

To check whether one of your lists contains a specific value, use the ContainsKey operator. Specify the list name, the column, and the key that you want to check for.

For example, you upload a single-column list of risky email addresses and name it Risky email list.

You can then use the following syntax to reject all transactions from the risky email addresses in this list.

RETURN Reject("risky email") 
WHEN ContainsKey("Risky email list", "Email", @"user.email")

This clause checks whether the "Email" column in the "Risky email list" list contains the @email key. If it does, the transaction is rejected.

Lookup

For multi-column lists, you can use the Lookup operator to check the value of a column for a specific key.

For example, you create a list that has one column for email addresses and another column that indicates the status of those email addresses. You name this list Email List.

You can then use the following syntax to reject all transactions from the email addresses in this list that have a status of Risky.

RETURN Reject("risky email") 
WHEN Lookup("Email List", "Email", @"user.email", "Status") == "Risky"

This clause looks for the @"user.email" key in the "Email" column in the "Email List" list and checks whether the value in the "Status" column is Risky. If it is, the transaction is rejected.

If the @"user.email" key isn't found in the list, Fraud Protection returns "Unknown."

You can also specify your own default value as the fifth parameter. For more information, see the Logical operators section earlier in this article.

The Lookup operator always returns a String value. To convert this value to an Int, Double, or DateTime value, use a type casting operator.

Using external calls, external assessments and velocities

• To reference an external call, type External, followed by the external call that you want to reference. For more information, see Use an external call in rules.
• To reference an external assessment, type Assessments, followed by the external assessment that you want to reference. For more information, see Use an external assessment in rules.
• To reference a velocity, type Velocity, followed by the velocity that you want to reference. For more information, see Use a velocity in rules.

Type inference of attributes

Variable types are inferred from the context that they're used in. Here are some examples:

• In the expression WHEN @isEmailValidated, the variable is interpreted as a Boolean value.
• In the expression Model.Risk().Score > 500, the variable is interpreted as a Double value.
• In the expression @"user.creationDate".Year < DateTime.UtcNow.Year, the variable is interpreted as a DateTime value.

If there isn't enough context to infer the type of a variable, it's considered a String value. For example, in the expression Model.Risk().Score < Model.Bot(@"deviceFingerprinting.id").Score, both variables are interpreted as strings.

To specify the type of a nonstring variable, use a type casting operator.

JSON arrays and objects

FQL has support for the construction of complex structured objects as local variables, which can be passed through to the external call or external assessment in JSON form. As with all other locals in FQL, arrays and objects are immutable once created.

JSON arrays

Arrays are created by enclosing expressions in a pair of brackets:

LET $arr1 = [ "hello", "world" ]
LET $arr2 = [
  "this is also an array",
  78.4,
  $arr1,
  @"user.email",
  External.MyExtcall()
]

JSON objects

Objects are created with braces:

LET $obj1 = { isObject: true }
LET $obj2 = {
  numberField: 7,
  fieldIs: "string",
  internalObj: $obj1,
  inline: {
    innerInnerField: "hello"
  }
}

FQL functions for JSON arrays and objects

Where myArr, in the examples above, is an array. The source of this array can be the @@payloadProperty, external assessment response, external call response, local variable, or a global variable.

The following are examples of how to use the syntax based on different array sources:

• Array source: Payload

LET $sample = @@"myArr[0]".AsJsonArray()   
RETURN Approve()   
WHEN $sample[0].AsString() == "a"

• Array source: Local variable

  LET $group1 =["a", "b", "c"]
  LET $group1 =[{ item1: "a", item2: "b"}, { item1: "c", item2: "d"}]
  LET $group3 =[{ item1: "a", item2: "b", item3: ["c", "d"]}, {{ item1: "e", item2: "f", item3: ["g", "h"]}]
  RETURN Approve()
  WHEN $group1[0].AsString() == "a" && $group1[0].item2.AsString() == "b" && $group3[0].item3[0].AsString() == "c" 
  

The following are some more detailed examples of how to use the above syntax based on different array sources:

Type casting for JSON arrays and objects

• The following .As<Type>() are supported from the JsonObject:

  • AsString()
  • AsInt()
  • AsDouble()
  • AsDateTime()
  • AsBool()
  • AsJsonArray()
  • AsJsonObject()

• When you use either of the two array helper methods, Array.GetValue or Arrays.GetValues, you need to type cast using .As<Type>(). Example:

  LET $arr = {myArr:[{item1: "red", number: 45}, {item1: "blue", number: 56}, {item1: "green", number: 33}]}
  LET $sample = Array.GetValues($arr.myArr.AsJsonArray(), "item1", "blue")
  

• Once you converted data to a JSON object or array explicitly, you can use .As<Type>() to cast to a different data type, if needed. Example:

  RETURN Approve()
  WHEN $sample[0].number.AsInt() == 56
  

• When you use @@, the data is implicitly type cast to a JSON object. If you then want to convert the JSON object to a different data type, you must use .As<Type>(). Example:

  LET $sample = @@”user.addresses”.AsJsonArray()
  

• When you want to output in a certain format, you must use .As<Type>(). Example:

  LET $sample = @@”user.addresses”
  Output(abc = $sample.AsJsonArray())
  

LET $sample = External.myCall().data[0].Item1[0].AsJsonArray()

Or

LET $sample = @@”accommodations[0].rooms”.AsJsonArray()

Functions available within Post Decision Actions

Following functions can be used within Post Decision Actions only. They aren't available within Decision Rules