Rule Expressions

On this page

Overview

Expression Syntax
Embedded Expressions
Multi-Field Expressions
Expression Evaluation
Expansions
Logical Expansions
Value Expansions
Environment Expansions
Request Expansions
User Expansions
MongoDB Document Expansions
Service Expansions
Operators
Convert EJSON Values
Call a Function
Check Existence
Compare Values

Overview

A rule expression is a JSON object that you write to control data access with rules. Each expression defines the conditions under which a user can take some action. For example, you can write an expression to control whether a user can read or write data in a MongoDB document or a synced realm.

When Atlas App Services evaluates a rule, it resolves each expression associated with the rule to a boolean value, either true or false.

You can define simple, static expressions that use hardcoded values:

A "static" expression that only matches the hardcoded ID

{ "id": "5f6aae9a82989d521a606369" }

You can also write expressions that support arbitrary logic to express dynamic requirements and complex or custom workflows. A dynamic expression can include variables that reflect the current context, called expansions, and can use built-in operators to transform data:

A "dynamic" expression that varies based on the requesting user and their IP location

{
  "owner": "%%user.id",
  "%%request.remoteIPAddress": {
    "$in": "%%values.allowedClientIPAddresses"
  }
}

Expression Syntax

An expression is either a boolean value (i.e. true or false) or a JSON object.

Expression object field names can be a value, an expansion, or an operator. Each field must contain one of a value, an expansion, or a nested expression.

Expression object have the following format:

{
  <Value | Expansion | Operator>: <Value | Expression>,
  ...
}

Embedded Expressions

You can embed multiple expression documents in the fields of another expression document to handle complex evaluation logic. App Services evaluates expressions depth-first, post-order, i.e. it starts at the bottom of the expression tree and works back to the root-level fields by evaluating each expression after all of its embedded expressions.

Example

This expression evaluates to true only if the number provided as the someNumber argument falls in a specific range.

{
  "%%args.someNumber": {
     "%and": [
        { "$gt": 0 },
        { "$lte": 42 }
     ]
  }
}

Multi-Field Expressions

When you have more than one field in an expression, that expression evaluates to true if and only if every field in the expression evaluates to true. In other words, App Services treats multiple fields in a single expression as an "AND" operation.

Example

This third-party service rule expression evaluates to true only if both the url argument was provided and the body.userId argument matches the id of the user that called the action.

{
  "%%args.url": { "$exists": true },
  "%%args.body.userId": "%%user.id"
}

Expression Evaluation

App Services evaluates expressions by first replacing expansions with their runtime values and then evaluating each field of the expanded expression document to a boolean expression. If all fields in an expression evaluate to true, the expression also evaluates to true.

Expression fields evaluate based on the following rules:

If an expanded field name matches its value, it evaluates to true.
If a field's value is an embedded expression, it evaluates to the same value as the embedded expression. See embedded expressions.

Note

If a rule does not explicitly use the %%args or %%root expansion, expression field names default to checking for arguments or document fields of the same name. For example, the expression { "url": "https://www.example.com" } defaults to evaluating the value against %%args.url in a service rule and %%root.url in a MongoDB rule.

Expansions

An expansion is a variable that represents a dynamic value in an expression. Expansions are denoted by two percent signs followed by the expansion name. They are:

%%root, which represents the data in a MongoDB document.
%%user, which represents a user interacting with your app.
%%request, which represents an incoming request.
%%values, which represents a static value.
%%environment, which represents your app's environment.
%%args, which represents the arguments that were passed to a service action.

When your app evaluates an expression, it replaces each expansion in the expression with a specific value determined by your app's configuration and the context at the time of evaluation.

Note

Some expansions, like %%user, are available in all expressions. Others are limited to specific contexts, like %%root which is only available in linked collection rule expressions.

Logical Expansions

%%true: Type: boolean
Usable In: Any Expression
Evaluates to true. Use this to assert that a nested expression must evaluate to true.

%%false: Type: boolean
Usable In: Any Expression
Evaluates to false. Use this to assert that a nested expression must evaluate to false.

Value Expansions

%%values

Type: object

Usable In: Any Expression

Represents your application's values. Each field of the object maps a value name to its corresponding JSON value or secret.

Example

The following expression evaluates to true if the value admin_ids is a list that contains the user's account ID:

{
  "%%user.id": { "$in": "%%values.admin_ids" }
}

Environment Expansions

%%environment

Type: object

Usable In: Any Expression

Represents the current environment. You can read the environment name (tag) and access environment values.

Each property of the object maps the name of an environment value to its value in the current environment.

{
  "tag": "<Environment Name>"
  "values": {
    "<ValueName>": <Value>
  }
}

Example

The following is a rule expression that evaluates to true if the current environment is "production" and the "baseUrl" environment value is defined:

{
  "%%environment.tag": "production",
  "%%environment.values.baseUrl": { "%exists": true }
}

Request Expansions

%%request

Type: object

Usable In: Any Expression

Represents the incoming request.

{
  "httpMethod": "<HTTP Method>",
  "httpReferrer": "<HTTP Referer Header>",
  "httpUserAgent": "<HTTP User Agent>",
  "rawQueryString": "<URL Query String>",
  "remoteIPAddress": "<IP Address>",
  "requestHeaders": {
    "<Header Name>": ["<Header Value>", ...]
  },
  "service": "<Service Name>",
  "action": "<Endpoint Function or Service Action Name>",
  "webhookUrl": "<HTTPS Endpoint Route>"
}

User Expansions

%%user

Type: object

Usable In: Any Expression

Represents the user that initiated the request. The user object contains account information, metadata from authentication providers, and custom data from your app.

{
  "id": "<User Account ID>",
  "type": "<normal | server>",
  "data": {
    "<Field Name>": <Value>,
    ...
  }
  "custom_data": {
    "<Field Name>": <Value>,
    ...
  }
  "identities": [
    {
      "providerType": "<Auth Provider Name>",
      "id": "<Provider User ID"
    }
}

%%user.id: Type: string
Usable In: Any Expression
The authenticated user's id.

%%user.type: Type: "normal" | "server"
Usable In: Any Expression
The type of user that initiated the request. Evaluates to "server" for API key users and "normal" for all other users.

%%user.custom_data

Type: object

Usable In: Any Expression

The user's custom data. The exact contents vary depending on your custom user data configuration.

Example

"custom_data": {
  "primaryLanguage": "English",
}

%%user.data

Type: object

Usable In: Any Expression

The user's metadata. The exact contents will vary depending on the authentication provider identities associated with the user.

Example

"data": {
  "name": "Joe Mango",
  "email": "joe.mango@example.com"
}

%%user.identities

Type: object[]

Usable In: Any Expression

A list of all authentication provider identities associated with the user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider's type:

Example

"identities": [
  {
    "id": "5bce299457c70db9bd73b8-aajddbkuvomsvcrjjfoxs",
    "providerType": "local-userpass"
  }
]

MongoDB Document Expansions

%%this: Type: any
Usable In: MongoDB Atlas Data Sources
The value of a particular field as it exists at the end of a database operation.

%%prev: Type: any
Usable In: MongoDB Atlas Data Sources
The value of a particular field before it is changed by a write operation.

%%root: Type: object
Usable In: MongoDB Atlas Data Sources
The full document as it exists at the end of a database operation.

%%prevRoot: Type: object
Usable In: MongoDB Atlas Data Sources
The full document before it is changed by a write operation.

Example

The following is a MongoDB schema validation expression that evaluates to true if either the document previously existed (i.e. the action is not an insert) or the document's status field has a value of "new":

{
  "%or": [
    { "%%prevRoot": { "%exists": %%true } },
    { "%%root.status": "new" }
  ]
}

Service Expansions

%%args

Type: object

Usable In: Third-Party Services [Deprecated]

A document containing the values passed as arguments to a service action. You can access each argument by its parameter name.

Example

The following is a Twilio service rule that evaluates to true if the sender's phone number (the from argument) matches a specific value:

{
  "%%args.from": "+15558675309"
}

%%partition: Type: string | number | BSON.ObjectId
Usable In: Partion-based Sync
(Partition-Based Sync only.) The partition key value of the current partition being evaluated.

Operators

An expression operator represents an action or operation within an expression. Operators take in one or more arguments and evaluate to a result value. The type and value of the result depends on the operator you use and the arguments you pass to it.

Expression operators are denoted by strings that begin with either a single percent sign (%) or a dollar sign ($). You can use them in any expression.

Convert EJSON Values

The following operators allow you to convert values between BSON/EJSON and JSON representations:

%stringToOid

Converts a 12-byte or 24-byte string to an EJSON objectId object.

Example

{
  "_id": {
    "%stringToOid": "%%user.id"
  }
}

%oidToString

Converts an EJSON objectId object to a string.

Example

{
  "string_id": {
    "%oidToString": "%%root._id"
  }
}

Important

No Inner Operations

%stringToOid and %oidToString do not evaluate JSON operators. You must provide either a literal string/EJSON object or an expansion that evaluates to one.

Call a Function

The following operators allow you to call functions in your App Services application:

%function

Calls a function with the specified name and arguments. Evaluates to the value that the function returns.

Example

{
  "%%true": {
    "%function": {
      "name": "isEven",
      "arguments": [42]
    }
  }
}

Check Existence

The following operators allow you to determine if a value exists in an object or array:

$exists

Checks if the field it is assigned to has any value. Evaluates to a boolean representing the result.

Example

{
  "url": { "$exists": true }
}

$in

Checks a specified array of values to see if the array contains the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "$in": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

$nin

Checks a specified array of values to see if the array does not contain the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "$nin": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

Compare Values

The following operators allow you to compare values, including expanded values:

$eq

Checks if the field it is assigned to is equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$eq": 42 } }

$ne

Checks if the field it is assigned to is not equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "numPosts": { "$ne": 0 } }

$gt

Checks if the field it is assigned to is strictly greater than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$gt": 0 } }

$gte

Checks if the field it is assigned to is greater than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$gte": 0 } }

$lt

Checks if the field it is assigned to is strictly less than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$lt": 0 } }

$lte

Checks if the field it is assigned to is less than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "$lte": 0 } }

← Filters Rule Templates & Examples →

Rule Expressions.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Overview

Expression Syntax

Embedded Expressions

Example

Multi-Field Expressions

Example

Expression Evaluation

Note

Expansions

Note

Logical Expansions

Value Expansions

Example

Environment Expansions

Example

Request Expansions

User Expansions

Example

Example

Example

MongoDB Document Expansions

Example

Service Expansions

Example

Operators

Convert EJSON Values

Example

Example

Important

No Inner Operations

Call a Function

Example

Check Existence

Example

Example

Example

Compare Values

Example

Example

Example

Example

Example

Example

Rule Expressions