Language guide for Fraud Protection rules

Overview

Microsoft Dynamics 365 Fraud Protection rules are written in a rich and expressive language. This language has many similarities to C# and SQL, and is designed to give you the power and flexibility that you need to customize your fraud strategy and enforce unique business policies.

To get started, read the Quick start guide that follows. For a complete list of available operators, see the Language reference later in this topic.

Quick start guide

Rules consist of clauses, and are defined by the RETURN and WHEN keywords. They have the following basic structure.

RETURN *decision* 
WHEN *condition is true*

The RETURN decision is run only if the WHEN expression is evaluated to True.

RETURN

Your clause must return a decision of Approve, Reject, Challenge, or Review. You can also include optional parameters to send more information about the decision. Here are some examples of RETURN statements.

RETURN Reject()
RETURN Reject("email is on block list")
RETURN Reject("email is on block list", "do not escalate")

For information about decision types and their parameters, see the Decision types section later in this topic.

In addition to a decision type, you can also return additional functions, such as Other or Trace.

RETURN Approve(), Other(key="someValue")
RETURN Review(), Trace(email=@"user.email")

For more information, see the Additional return types section later in this topic.

WHEN

A WHEN expression contains one or more Boolean expressions. You can create multiple Boolean expressions by using the AND (&&) and OR (||) joining operators.

A Boolean expression is formed by checking and/or comparing two types of variables:

  • The payload values of the fields that are included in an application programming interface (API) request for a purchase.
  • The scores that are generated from Fraud Protection's artificial intelligence (AI) models.

You can access variables using the following syntax: @"object.field". For example, @"user.firstName".

When you use variables in a Boolean expression, you can perform the following tasks:

  • Compare variables to other variables, or to constants.
WHEN @"user.email" == "kayla@contoso.com"
WHEN @"user.firstName" == @"shippingAddress.firstName"
WHEN @"riskscore" > 700 
WHEN Geo.CountryCode(@"device.ipAddress") == "US"
  • Check whether a variable is contained in a list.
WHEN ContainsKey("Safe List", "Emails", @"user.email")
  • Check the value of a key in a list.
WHEN Lookup("Email List", "Emails", @"user.email", "Status") == "Safe"
WHEN Lookup("Product cutoff list", "Product", @"productList.productName", "Score Cutoff").toDouble() < @"riskScore"
  • Evaluate a string.
WHEN @"phone.phoneNumber".StartsWith("1-")
WHEN @"user.email".EndsWith("@contoso.com")

Language reference

This section contains a complete list of operators that are available in Fraud Protection. These operators are grouped into the following types:

Keywords

Keyword Description Example
RETURN

This keyword must be followed by a valid decision type: Approve, Reject, Challenge, or Review.

The decision can be followed by an additional return type such as Other or Trace.

RETURN Reject()

RETURN Reject(), Other(key=@"user.email")

RETURN Reject(), Trace(ip=@"device.ipAddress")

WHEN The expression must be able to be evaluated to a Boolean value. WHEN @"riskscore" > 400

Decision types

Decision type Description Example
Approve

This decision type approves the event.

Overloads:

  • Approve()
  • Approve(String reason)
  • Approve(String reason, String supportMessage)

Approve()

Approve("on safe list")

Approve ("on safe list", "do not escalate")

Reject

This decision type rejects the event.

Overloads:

  • Reject()
  • Reject(String reason)
  • Reject(String reason, String supportMessage)

Reject()

Reject("embargo country")

Return Reject()

Reject("embargo country", "do not escalate")

Review

This decision type marks the transaction for further review.

Overloads:

  • Review()
  • Review(String reason)
  • Review(String reason, String supportMessage)

Review()

Review("user on watch list")

Review("user on watch list", "do not escalate")

Challenge

This decision type marks the transaction for further verification by using the specified challenge type.

Overloads:

  • Challenge(String challengeType)
  • Challenge(String challengeType, String reason)
  • Challenge(String challengeType, String reason, String supportMessage)

Challenge ("SMS")

Challenge ("SMS", "suspected bot")

Challenge ("SMS", suspected bot", "do not escalate")

Additional return types

Return type Description Example
Other This type can be used to pass key/value pairs. Other(key="test", email=@"user.email", countryRegion=Geo.CountryRegion(@"device.ipAddress"))
Trace Can be used to trigger a Trace event, and send key value pairs to the FraudProtection.Trace.Rule Event Tracing namespace. Trace(key="Manual Review", ip=@"device.ipAddress")

Variables

For information about how to use variables, see the Type inference of variables section later in this topic.

Variable Description Example
@

Used to reference a variable from the event payload.

After the @, specify the full path of the variable you would like to reference, surrounded by quotes. For example, @"address.city".

If the variable referenced is not part of the event payload, the default value for that type is returned – 0.0 for double, empty string for strings, etc.

The type of the variable is inferred by the context in which it is used. If not enough context is provided, the type defaults to String.

For information about type inference, see Type inference of variables.

@"address.city"

@"botScore"

For every Account Protection event, Fraud Protection's AI models generate a bot score between 0 and 999. A higher score indicates a higher probability that the event was initiated by a bot.

You can use @botScore to reference this score in post-bot-scoring clauses and post-risk-scoring clauses.

@"botScore"
@"riskScore"

For every Purchase and Account Protection event, Fraud Protection's AI models generate a risk score between 0 and 999. A higher score indicates a higher risk.

You can use @riskScore to reference this score in post-risk-scoring clauses.

@"riskScore"
@a[x]

Used to index array variables.

If the request payload for an assessment contains an array of items, you can access individual elements of the array using the following syntax: @"productList[0]".

To access an attribute of that element: @"productList[0].productId"

@"productList[0].productId"

@"paymentInstrumentList[3].type"

Joining operators

Operator Description Example
AND (&&) Logical And

@"botScore" > 500 && @"riskScore" > 500

@"botScore" > 500 AND @"riskScore" > 500

OR (||) Logical Or

@"email.isEmailUsername" == false || @"email.isEmailValidated" == false

@"email.isEmailUsername" == false OR @"email.isEmailValidated" == false

List operators

For information about how to use lists in rules, see the Using lists in rules section later in this topic.

Operator Description Example
ContainsKey

This operator checks whether a key is contained in the specified column in a predefined list.

ContainsKey(String listName, String columnName, String key)

ContainsKey("Email Support List", "Emails", @"user.email")

This example checks whether the "Emails" column in the "Email Support List" list contains the @"user.email" variable.

Lookup

This operator looks up the value of a key in a list column and returns the value as a String value.

If the key isn't found, and defaultValue isn't specified, "Unknown" is returned.

Overloads:

  • Lookup(String listName, String keyColumnName, String key, String valueColumnName)
  • Lookup(String listName, String keyColumnName, String key, String valueColumnName, String defaultValue)

Lookup("Email Support List", "Emails", @"user.email", "Status")

This example looks for the @"user.email" variable in the "Emails" column of the "Email Support List" list and returns the corresponding value in the "Status" column.

LookupClosest

This operator looks up the value of a key in a list column. If the key isn't found, it returns the value of the key that is alphabetically closest to the key that you're looking for.

Lookup(String listName, String keyColumnName, String key, String valueColumnName)

LookupClosest("IP Addresses", "IP", @"device.ipAddress", "City") == "Seattle"

This example looks for the @ipAddress variable in the "IP" column of the "IP Addresses" list and returns the corresponding value in the "City" column. If @ipAddress isn't found in the list, the expression returns the value of the next closest IP address in the list.

In

This operator checks whether a key is contained in a comma-separated list of values.

In(String key, String list)

In(@"user.countryRegion", "US, MX, CA")

Comparison operators

Fraud Protection supports all standard C# comparison and equality operations. Applying these operators to Strings will result in lexicographic comparisons. This table includes some examples of operators which may be useful to you.

Operator Description Example
== This operator checks for equality. @"user.countryRegion" == @"shippingAddress.countryRegion"
!= This operator checks for inequality. @"user.countryRegion" != @"shippingAddress.countryRegion"
> This operator checks whether the first value is greater than the second value. @"riskScore" > 500
< This operator checks whether the first value is less than the second value. @"riskScore" < 500
>= This operator checks whether the first value is greater than or equal to the second value. @"riskScore" >= 500
<= This operator checks whether the first value is less than or equal to the second value. @"riskScore" <= 500

Geo operators

These operators convert an IP address to a geographical address.

Operator Description Example
Geo.RegionCode

This operator converts an IPv4 address to its US region code (that is, the abbreviation for the name of the US state or territory).

For example, for an IP address in Washington state, "WA" is returned.

Geo.RegionCode(@"device.ipAddress")
Geo.Region

This operator converts an IPv4 address to its US region (that is, the name of the US state or territory).

For example, for an IP address in Washington state, "Washington" is returned.

Geo.Region(@"device.ipAddress")
Geo.CountryCode

This operator converts an IPv4 address to its country/region code.

For example, for an IP address in Australia, "AU" is returned.

Geo.CountryCode(@"device.ipAddress")
Geo.CountryRegion

This operator converts an IP address to a region name.

For example, for an IP address in Australia, "Australia" is returned.

Geo.CountryRegion(@"device.ipAddress")
Geo.City

This operator converts an IPv4 address to a city name.

For example, for an IP address in New York City, "New York City" is returned.

WGeo.City(@"device.ipAddress")
Geo.MarketCode

This operator converts an IPv4 address to the market code of the IP address.

For example, for an IP address from Canada, "NA" (North America) is returned.

Geo.MarketCode(@"device.ipAddress")

String operators

Fraud Protection supports all standard .NET string operators. This table includes some examples of methods that you might find useful.

Operator Description Example
StartsWith

This operator checks whether a string begins with a specified prefix.

StartsWith(String prefix)

@"user.phoneNumber".StartsWith("1-")
EndsWith

This operator checks whether a string ends with a specified suffix.

EndsWith(String suffix)

@"user.email".EndsWith("@contoso.com")
Contains

This operator checks whether a string contains another string.

Contains(String substring)

@"productList.productName".Contains("Xbox")
Exists

This operator checks whether a variable exists in the event payload.

Exists(String variable)

Exists(@"user.email")

Math operators

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

Operator Description Example
Math.Min

This operator computes the minimum of two values.

Math.Min(Double value1, Double value2)

Math.Min(@"riskScore",@"botScore")
Math.Max

This operator computes the maximum of two values.

Math.Max(Double value1, Double value2)

Math.Max(@"riskScore",@"botScore")

DateTime operators

Fraud Protection supports all standard .NET DateTime properties, methods, and operators. This table includes some examples of properties that you might find useful.

Operator Description Example
DaysSince

Returns an int representing the number of days that have passed between today (in UTC time) and the given DateTime value.

DaysSince(DateTime date)

DaysSince(@"user.CreationDate")
UtcNow This operator gets a DateTime object that is set to the current date and time on the computer, expressed as Coordinated Universal Time (UTC). DateTime.UtcNow
Today This operator gets an object that is set to the current date, where the time component is set to 00:00:00. DateTime.Today
Year This operator gets the year component of the date that is represented by this instance. @"user.creationDate".Year
Date This operator gets a new object that has the same date as this instance, and the time value. @"user.creationDate".Date

Type casting operators

For information about type inferencing, see the Type inference of variables section.

Operator Description Example
ToDateTime() This operator converts a string to a DateTime object. @"user.creationDate".ToDateTime()
ToDouble() This operator converts a string to a Double value. @"productList.purchasePrice".ToDouble()
ToInt32() This operator converts a string to an Int32 value. @"riskScore".ToInt32()

Using lists in rules

You can use the ContainsKey and Lookup operators to create a rule with a previously created list.

ContainsKey

To check whether a 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 example, you create a single-column list of risky email addresses and name it Risky email list.

Email
Kayla@contoso.com
Jamie@bellowscollege.com
Marie@atatum.com

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

You can use the Lookup operator to look up the value of a key in a list.

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.

Email Status
Kayla@contoso.com Risky
Jamie@bellowscollege.com Risky
Marie@atatum.com Risky
Camille@fabrikam.com Safe
Miguel@proseware.com Safe
Tyler@contoso.com Safe

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 List operators section earlier in this topic.

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

Type inference of variables

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

  • In the expression WHEN @isEmailValidated, the variable is interpreted as a Boolean value.
  • In the expression @"riskScore" > 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 @"riskScore" < @"botScore", both variables are interpreted as strings.

To specify the type of a non-string variable, use a type casting operator.

Note

Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).