Navigation

Triggers

Introduction

MongoDB Stitch triggers enable you to process and react to events in your application as they occur. You can automatically respond to changes in a MongoDB collection with a database trigger or execute additional server-side logic when a user is created, authenticated, or deleted with an authentication trigger.

Triggers listen for application events of a configured type and are each linked with a specific Stitch function. Whenever a trigger observes an event that matches your configuration, it “fires” and passes the event object that caused it to fire as the argument to its linked function. You can configure the events that cause a trigger to fire based on their operation type as well as other values specific to each type of trigger.

Note

Stitch limits the execution of trigger functions to a rate of 50 executions per second across all triggers in an application. If additional triggers fire beyond this threshold, Stitch adds their associated functions to a queue and executes the functions once capacity becomes available.

Examples

Database Trigger

An online store wants to notify its customers whenever one of their orders changes location. They record each order in the store.orders collection as a document that resembles the following:

{
  _id: ObjectId("59cf1860a95168b8f685e378"),
  customerId: ObjectId("59cf17e1a95168b8f685e377"),
  shipDate: ISODate("2018-06-27T16:20:42.313Z"),
  orderContents: [
    { qty: 1, name: "Earl Grey Tea Bags - 100ct" }
  ],
  shippingLocation: [
    { location: "Memphis", time: ISODate("2018-06-27T18:22:33.243Z") },
  ]
}

To automate this process, the store creates a database trigger that listens for UPDATE change events in the store.orders collection. When the trigger observes an UPDATE event, it passes the change event object to its associated function, textShippingUpdate. The function checks the change event for any changes to the shippingLocation field and, if it was updated, sends a text message to the customer with the new location of the order.

../_images/trigger-location-updater.png
Trigger Configuration
{
  "type": "DATABASE",
  "name": "shippingLocationUpdater",
  "function_name": "textShippingUpdate",
  "config": {
    "service_name": "mongodb-atlas",
    "database": "store",
    "collection": "orders",
    "operation_types": ["UPDATE"],
    "full_document": true,
    "match": {}
  },
  "disabled": false
}
textShippingUpdate
exports = async function (changeEvent) {
  // Destructure out fields from the change stream event object
  const { updateDescription, fullDocument } = changeEvent;

  // Check if the shippingLocation field was updated
  const updatedFields = Object.keys(updateDescription.updatedFields);
  const isNewLocation = updatedFields.some(field =>
    field.match(/shippingLocation/)
  );

  // If the location changed, text the customer the updated location.
  if (isNewLocation) {
    const { customerId, shippingLocation } = fullDocument;
    const twilio = context.services.get("twilio");
    const mongodb = context.services.get("mongodb-atlas");
    const customers = mongodb.db("store").collection("customers");

    const { location } = shippingLocation.pop();
    const customer = await customers.findOne({ _id: customer_id })
    twilio.send({
      to: customer.phoneNumber,
      from: context.values.get("ourPhoneNumber"),
      body: `Your order has moved! The new location is ${location}.`
    });
  }
};

Authentication Trigger

An online store wants to store custom metadata for each of its customers in MongoDB. Each customer should have a document in the store.customers collection where metadata about them can be recorded and queried.

To guarantee that each customer is represented in the collection, the store creates an authentication trigger that listens for newly created users in the email/password authentication provider. When the trigger observes a CREATE event, it passes the authentication event object to its linked function, createNewUserDocument. The function creates a new document describing the user and their activity and inserts it into the store.customers collection.

../_images/trigger-example-new-user.png
Trigger Configuration
{
  "type": "AUTHENTICATION",
  "name": "newUserHandler",
  "function_name": "createNewUserDocument",
  "config": {
    "providers": ["local-userpass"],
    "operation_type": "CREATE"
  },
  "disabled": false
}
createNewUserDocument
exports = async function(authEvent) {
  const mongodb = context.services.get("mongodb-atlas");
  const customers = mongodb.db("store").collection("customers");

  const { user, time } = authEvent;
  const newUser = { ...user, eventLog: [ { "created": time } ] };
  await customers.insertOne(newUser);
}