Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services

Trigger Configuration Files

On this page

  • General Configuration
  • Database Triggers
  • Authentication Triggers
  • Scheduled Triggers

Note

This page describes a legacy configuration file format. You should only use this information if you're using the deprecated realm-cli.

Any configuration files you pull with App Services CLI or export from the UI use the latest configuration version. For detailed information on the current configuration file format, see App Configuration.

app/
└── triggers/
    └── <trigger name>.json

General Configuration

All triggers conform to a base schema with specific variations depending on the trigger type. The following fields exist in all trigger configuration files:

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "<Trigger Type>",
  "config": {},
  "function_name": "<Trigger Function Name>",
  "disabled": <Boolean>
}
Field
Description
name
String
The trigger name. This may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens.
type
String

The trigger type. The value of this field determines the exact configuration file schema.

Valid Options:

  • "DATABASE"

  • "AUTHENTICATION"

  • "SCHEDULED"

config
Document

A document with fields that map to additional configuration options for the trigger. The exact configuration fields depend on the trigger type:

function_name
String
The name of the Atlas Function that the trigger executes whenever it fires.
event_processors
Document

A document that configures the trigger to send events to external event processors whenever it fires. Cannot be used with function_name.

For more information, see Send Trigger Events to AWS EventBridge.

disabled
Boolean
If true, the trigger will not listen for any events and will not fire.

Database Triggers

Database trigger configurations conform to the base trigger schema with additional configuration options that specify which collection to watch and when to fire the trigger. The following fields exist in database trigger configuration files:

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "DATABASE",
  "config": {
    "service_name": "<MongoDB Service Name>",
    "database": "<Database Name>",
    "collection": "<Collection Name>",
    "operation_types": ["<Operation Type>", ...],
    "full_document": <boolean>,
    "full_document_before_change": <boolean>,
    "tolerate_resume_errors": <boolean>,
    "unordered": <boolean>,
    "match": { <Match Filter> },
    "project": { <Projection Filter> },
  },
  "function_name": "<Trigger Function Name>",
  "disabled": <Boolean>
}
Field
Description
config.service_name
String
The name of the MongoDB data source that contains the watched collection. You cannot define a database trigger on a serverless instance or Federated database instance.
config.database
String
The name of the MongoDB database that contains the watched collection.
config.collection
String
The name of the collection that the trigger watches.
config.operation_types
String[]

A list of one or more database operation types that cause the trigger to fire.

Valid operations types:

  • "INSERT"

  • "UPDATE"

  • "REPLACE"

  • "DELETE"

Tip

Update operations executed from MongoDB Compass or the MongoDB Atlas Data Explorer fully replace the previous document. As a result, update operations from these clients will generate REPLACE change events rather than UPDATE events.

config.full_document
Boolean

If true, UPDATE change events include the latest majority-committed version of the modified document after the change was applied in the fullDocument field.

Note

Regardless of this setting:

  • INSERT and REPLACE events always include the fullDocument field.

  • DELETE events never include the fullDocument field.

config.full_document_before_change
Boolean

If true, change events include a copy of the modified document from immediately before the change was applied in the fullDocumentBeforeChange field. All change events except for INSERT events include the document preimage.

Important

Collection-Level Preimage Settings

Document preimages use extra information stored in the oplog. The extra data may have performance implications for some apps.

Once you've enabled document preimages for any trigger on a given collection, that collection will include preimage data in the oplog and other triggers on the collection can use preimages with no additonal overhead.

You can disable document preimages on a per-trigger basis to exclude the preimage from change events. Regardless of your trigger-level settings, a collection's oplog entries will continue to include preimage data unless you explicitly disable preimages for the collection.

For more information, see Document Preimages.

config.tolerate_resume_errors
Boolean

If true, the Trigger automatically resumes if the token required to process change stream events cannot be found.

If enabled, when this Trigger's resume token cannot be found in the cluster's oplog, the Trigger automatically resumes processing events at the next relevant change stream event. All change stream events from when the Trigger was suspended until the Trigger resumes execution do not have the Trigger fire for them.

For more information on resuming suspended Triggers, see Suspended Triggers.

config.unordered
Boolean

If true, indicates that event ordering is disabled for this trigger.

If event ordering is enabled, multiple executions of this Trigger will occur sequentially based on the timestamps of the change events. If event ordering is disabled, multiple executions of this Trigger will occur independently.

Tip

Performance Optimization

Improve performance for Triggers that respond to bulk database operations by disabling event ordering. Learn more.

config.match
Document

A $match expression document that App Services uses to filter which change events cause the Trigger to fire. The Trigger evaluates all change event objects that it receives against this match expression and only executes if the expression evaluates to true for a given change event.

Note

Use Dot-Notation for Embedded Fields

MongoDB performs a full equality match for embedded documents in a match expression. If you want to match a specific field in an embedded document, refer to the field directly using dot-notation. For more information, see Query on Embedded Documents in the MongoDB server manual.

Tip

Performance Optimization

Limit the number of fields that the Trigger processes by using a $match expression. Learn more.

config.project
Document

A $project expression that selects a subset of fields from each event in the change stream. You can use this to optimize the trigger's execution.

The expression is an object that maps the name of fields in the change event to either a 0, which excludes the field, or a 1, which includes it. An expression can have values of either 0 or 1 but not both together. This splits projections into two categories, inclusive and exclusive:

  • An inclusive project expression specifies fields to include in each change event document. The expression is an object that maps the name of fields to include to a 1. If you don't include a field, it is not included in the projected change event.

    Example

    The following projection includes only the _id and fullDocument fields:

    {
      _id: 1,
      fullDocument: 1
    }

  • An exclusive project expression specifies fields to exclude from each change event document. The expression is an object that maps the name of fields to include to a 0. If you don't exclude a field, it is included in the projected change event.

    Example

    The following projection excludes the _id and fullDocument fields:

    {
      _id: 0,
      fullDocument: 0
    }

    Note

    You cannot exclude the operation_type field with a projection. This ensures that the trigger can always check if it should run for a given event's operation type.

Authentication Triggers

Authentication trigger configurations conform to the base trigger schema with additional configuration options that specify which auth providers to watch and when to fire the trigger. The following fields exist in authentication trigger configuration files:

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "AUTHENTICATION",
  "config": {
    "operation_type": ["<Operation Type>", ...],
    "providers": ["<Provider Type>", ...],
  },
  "function_name": "<Trigger Function Name>",
  "disabled": <Boolean>
}
Field
Description
config.operation_type
String

The authentication operation type that causes the trigger to fire.

Valid operations types:

  • "LOGIN"

  • "CREATE"

  • "DELETE"

config.providers
String[]

A list of authentication provider types that the trigger watches.

Valid provider types:

  • "anon-user"

  • "local-userpass"

  • "api-key"

  • "custom-token"

  • "custom-function"

  • "oauth2-facebook"

  • "oauth2-google"

  • "oauth2-apple"

Scheduled Triggers

Scheduled trigger configurations conform to the base trigger schema with additional configuration options that specify the schedule on which the trigger fires. The following fields exist in scheduled trigger configuration files:

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "SCHEDULED",
  "config": {
    "schedule": "<CRON expression>"
  },
  "function_name": "<Trigger Function Name>",
  "disabled": <Boolean>
}
Field
Description
config.schedule
String
The CRON expression that schedules the trigger's execution.

Next

What are the Atlas Application Services?