Navigation

Event Triggers Overview

Introduction

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

To get started with event triggers in your application, follow our guide to Create and Configure Triggers.

Application Events

Application events represent individual actions in some part of your application. There are two types of application event: database events, which represent a change in a linked MongoDB collection, and authentication events, which represent a user interacting with an authentication provider.

For details on each application event type, see the Application Events reference page.

Triggers

Triggers listen to all application events of a specific 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 event type.

For details on the configuration of triggers for each event type, see the trigger configuration reference section.

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 Event 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 event trigger that listens for UPDATE change events in the store.orders collection. When the trigger observes an UPDATE event, it passes the change event 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 Event 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 event trigger that listens for newly created users in the email/password authentication provider. When the trigger observes a CREATE event, it passes the 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);
}