Navigation

Expansions

Expansions are special variables for use with MongoDB Stitch rules.

General

The following expansions are available in any rule in any MongoDB Stitch app.

Name Type Description
%%true
boolean True.
%%false
boolean False.
%%user
document Holds user information. See %%user object.
%%values
any Expand a value (e.g. %%values.foo)
%function
returned value Execute a function defined in the MongoDB Stitch app.

MongoDB-Specific

The following expansions are for use in MongoDB service rules rules. %%this and %%prev represent document fields, while %%root and %%prevRoot represent documents. %%prev and %%prevRoot represent the original values of fields and documents which are changed after write operations.

Name Type Description
%%this
any Field value as it exists at the end of a database operation.
%%root
document Root document as it exists at the end of a database operation.
%%prev
any Field value referenced in a rules expression before it is changed by a write operation (insert, update, delete).
%%prevRoot
document Root document referenced in a rules expression before it is changed by a write operation.

The %%user Object

The %%user object has several fields with information about the app user.

Name Type Description
%%user.id
String User’s ID.
%%user.type
String Evaluates to "server" if the user request comes via an API key. Evaluates to "normal" for other user requests (via OAuth2, SAML, local, or anonymous).
%%user.data
document User metadata, including name and email (via login authentication).
%%user.identities
array A list of all identities associated with a MongoDB Stitch user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider’s name.

Examples

The %%user Object

The %%user object is useful for identifying users in database rules. When an app user logs in to an app, the %%user object is populated with the user’s authentication information, which can include name and ID.

The following database rule example evaluates to true only if the owner_id field value matches the value of %%user.id and the owner_name field value matches the value of %%user.data.name.

{
  "owner_id": "%%user.id",
  "owner_name": "%%user.data.name"
}

An app can allow certain actions, such as updating and deleting, to be taken only by a document’s owner. Other users may only have permission to perform other actions, such as reading. The above rule allows the app to distinguish between the owner and other users.

MongoDB Validation Rule

The following example is a MongoDB validation rule. It evaluates to valid if either:

  • The document already exists
  • The value specified in the name field of the document is not in the name array which is part of the named value myBoards.
{
  "%or": [
    {
      "%%prevRoot": {
        "%exists": %%true
      }
    },
    {
      "%%root.name": {
        "%nin": "%%values.myBoards.name"
      }
    }
  ]
}

%%this

The %%this object refers to the current document or field. This expansion is typically used to construct field and document-level permissions on a database collection. For example, the following MongoDB service write rule verifies that the value of a field is greater than 3 before allowing a write to the collection.

{ "%%this": { "%gt": 3 } }

Calling a Function

The result of a function can be used in rule. Functions are called with the %function expansion. The following example evaluates to valid if the user’s id is found in a predefined admins value.

The following function is defined as checkAuth:

The function returns true if and only if the current user’s is contained in the admins value.

A rule can use this function to check authentication as follows:

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