Navigation

Trigger Configuration Files

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

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 Realm 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 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>,
"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.
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"
config.full_document
Boolean

If true, UPDATE change events include the most current majority-committed version of the modified document in the fullDocument field.

Note

INSERT and REPLACE events always include the fullDocument field. DELETE events never include the fullDocument field. For more information, see the change events reference page.

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.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

Consider disabling event ordering if your trigger fires on a collection that receives short bursts of events (e.g. inserting data as part of a daily batch job).

Ordered Triggers wait to execute a Function for a particular event until the Functions of previous events have finished executing. As a consequence, ordered Triggers are effectively rate-limited by the run time of each sequential Trigger function. This may cause a significant delay between the database event and the Trigger firing if a sufficiently large number of Trigger executions are currently in the queue.

Unordered Triggers execute functions in parallel if possible, which can be significantly faster (depending on your use case) but does not guarantee that multiple executions of a Trigger Function occur in event order.

config.match
Document

A $match expression document that Realm 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.

Example

The following Match Expression configures a trigger to fire only if the change event object specifies that the status field in a document changed.

{
"updateDescription.updatedFields.status": {
"$exists": true
}
}
config.project
Document

A $project expression document that Realm uses to filter the fields that appear in change event objects.

Example

A trigger is configured with the following Project Expression:

{
"_id": 0,
"operationType": 1,
"updateDescription.updatedFields.status": 1
}

The change event object that Realm passes to the trigger function only includes the fields specifed in the projection, as in the following example:

{
"operationType": "update",
"updateDescription": {
"updatedFields": {
"status": "InProgress"
}
}
}

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 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.
Give Feedback