Docs Menu

Docs Home → Atlas App Services

Trigger Configuration Files

On this page

  • General Configuration
  • Database Triggers
  • Authentication Triggers
  • Scheduled Triggers
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>",
  "disabled": <Boolean>,
  "config": {},
  "event_processors": {
    "<Type of Event Processor>": {
      "config": {}
    }
  }
}
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"

disabled
boolean
Defaults to false. If true, the trigger will not listen for any events and will not fire.
config
object

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

event_processors
object

A document that configures the trigger to send events to an event processor whenever it fires.

Valid Options:

  • "FUNCTION"

  • "AWS_EVENTBRIDGE"

For more information on Functions, see Atlas Functions.

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

event_processors.config
object

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

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. There are two possible configurations depending on the event processor type:

  • FUNCTION

  • AWS_EVENTBRIDGE

Database Trigger with a Function Event Processor

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "DATABASE",
  "disabled": <boolean>,
  "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> },
    "maximum_throughput": <boolean>,
    "skip_catchup_events": <boolean>,
    "project": { <Projection Filter> },
  },
  "event_processors": {
     "FUNCTION": {
         "config": {
             "function_name": "<Function Name>"
         }
     }
  }
}

Database Trigger with an AWS EventBridge Event Processor

triggers/<trigger name>.json
{
  "name": "<Trigger Name>",
  "type": "DATABASE",
  "disabled": <boolean>,
  "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> },
    "maximum_throughput": <boolean>,
    "skip_catchup_events": <boolean>,
    "project": { <Projection Filter> },
  },
  "event_processors": {
    "AWS_EVENTBRIDGE": {
      "config": {
        "account_id": "<AWS Account ID>",
        "region": "<AWS Region>",
        "extended_json_enabled": <boolean>
      }
    }
  },
  "error_handler": {
    "config": {
      "enabled": <boolean>,
      "function_name": "<Error Handler Function Name>"
    }
  }
}
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 for all triggers:

  • "INSERT"

  • "UPDATE"

  • "REPLACE"

  • "DELETE"

Valid operations types for database and deployment triggers:

  • "CREATE_COLLECTION"

  • "MODIFY_COLLECTION"

  • "RENAME_COLLECTION"

  • "SHARD_COLLECTION"

  • "DROP_COLLECTION"

  • "RESHARD_COLLECTION"

  • "REFINE_COLLECTION_SHARD_KEY"

  • "CREATE_INDEXES"

  • "DROP_INDEXES"

Valid operations types for deployment triggers only:

  • "DROP_DATABASE"

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
object

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.maximum_throughput
boolean
Defaults to false. If true, you can increase the maximum throughput beyond the default 10,000 concurrent processes. For more information, see Maximize Throughput Triggers.
config.skip_catchup_events
boolean
Defaults to false. If true, enabling the Trigger after it was disabled will not invoke events that occurred while the Trigger was disabled.
config.project
object

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.

event_processors.config.account_id
string
An AWS account ID. For more information on how to find the account ID, refer to Setup the MongoDB Partner Event Source.
event_processors.config.region
string
An AWS region.
event_processors.config.extended_json_enabled
boolean

false by default. If true, extended JSON is enabled.

Triggers convert the BSON types in event objects into standard JSON types. To preserve BSON type information, you can serialize event objects into Extended JSON format instead. Extended JSON preserves type information at the expense of readability and interoperability.

error_handler.config.enabled
boolean
If true, error handling is enabled for the AWS EventBridge trigger. For more information on configuring error handling, refer to Custom Error Handling.
error_handler.config.function_name
string
The name of the error handler function invoked when the AWS EventBridge trigger fails and cannot be successfully retried.

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.
← Atlas Device Sync Configuration Files
Value Configuration Files →

On this page