Navigation

Service Rules

To perform any service action in MongoDB Stitch, you must specify a rule for that particular service which enables the action. Service rules define the types of actions that can be executed by a particular service, and they also define the scopes of those actions.

The following list shows several examples of what service rules can do to limit the scope of a service action:

  • a Twilio service rule that only lets users send a text message with a specific message body.
  • a Amazon SES service rule that only allows users with certain IDs to send email messages.
  • a Twilio service rule that only allows messages where the recipient phone number is on a list of numbers that the current user is authorized to send messages to.
  • an HTTP service rule that only allows POST and PUT requests to a particular domain.

If there are no rules specified for a service, then no actions can be performed by that service.

Specifying a Rule

To add a rule to a particular service,

  1. Navigate to the Services page, which can be accessed from the navigation sidebar on the left-hand side of the MongoDB Stitch admin console.

  2. Click on the service for which you’d like to specify a rule.

  3. Click on the Rules tab of the service.

  4. Click New Rule, specify a name for the rule in the textbox that appears, and click Add Rule to confirm the creation of the new rule.

  5. Click on the newly created rule in the rules list on the left-hand side of the page.

  6. In the list of Actions, select all of the actions that you would like to enable with this service rule.

  7. In the When box, specify a JSON rule expression that will evaluate to true when you want the action to be permitted. If you specify {}, the expression will always evaluate to true and you can perform the action in any scenario.

    If you want a more nuanced rule, read the next section for an overview of how to build this rule expression. You can also look at the example service rules in the documentation page for the service you are creating a rule for.

  8. Click Save to save the changes you made to the rule.

Rule Expression Syntax

The general structure of a JSON rule expression is as follows:

{
  <field1>: <value1|expression1>,
  <field2>: <value2|expression2>,
  ...
}

Each field in this JSON document evaluates to a boolean. For the entire rule expression to evaluate to true, each field must evaluate to true. You can think of the overall rule expression as an AND of all of the boolean results of each field.

A field in the JSON expression can test for a variety of conditions, and the syntax is very similar to MongoDB query syntax.

The following are permitted in a service rule:

  • The arguments to the service action, available in the "%%args" expansion. For example, to access to the to argument of a Twilio send action, you could use "%%args.to".

    • This is useful when you want to restrict the use of a service based on its arguments.
    • The documentation page for each partner service lists the available arguments.
    • If you are using the argument as a field, you can omit the "%%args" expansion and just use the name of the argument, but only if you are not using the "%%args" prefix anywhere else in the rule.
  • The expansions that are permitted in rules across MongoDB Stitch.

    • This is useful when you want to use information about the current user to determine whether an action should be performed (via the "%%user" expansion.

    • This is also useful if you want write your rule evaluation logic as a function using the "%function" expansion.

      The following rule sends the service action arguments to a function named someFunction and uses the return value of the function as the result of the overall rule expression:

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

      The function itself then has access to the context object, which can also be useful for your rules.

  • Query expression operators with the exception of the $text and Geospatial operators

Each partner service’s documentation page contains examples of rules that can help you understand how the syntax works. These sample rules are also a good starting point for building your own rules.

Using Multiple Rules

If you plan on specifying multiple rules for a service, it’s important to understand that the multiple rules are effectively being OR’ed together, not AND’ed together.

When you call a service action from a function or from a client SDK, MongoDB Stitch checks each rule for that service until it finds one that allows that action. This means that if you have multiple rules, only one of the rules has to evaluate to true for the action to be permitted.

For example, imagine you have the following two rules that enable a send action for a Twilio service:

{
  "%%args.to": "+15551234567",
  "%%args.body": "This is the first rule.",
}


{
  "%%args.body": "This is the second rule.",
}

With these two rules, a text message with the body of "This is the second rule." can be sent to any number, even though there is a rule that restricts "%%args.to" to be "+15551234567". This is because the rules are checked independently of one another, and in the case of a message with the body of "This is the second rule.", the second rule will always evaluate to true, regardless of sender or recipient.