Send Trigger Events to AWS EventBridge

Create a New Error Handler

From the Configure Error Function section of the Create a Trigger page, select + NewFunction.

You can also select an existing Function, if one is already defined, from the dropdown.

Name the New Function

Enter a unique identifying name for the Function in the Name field. This name must be distinct from all other Functions in the application.

Write the Function Code

In the Function section, write the JavaScript code directly in the Function editor. The Function editor contains a default Function that you can edit as needed. For more information on creating Functions, refer to the Functions documentation.

Test the Function

In the Testing Console tab beneath the Function editor, you can test the Function by passing in example values to the error and changeEvent parameters, as shown in the comments of the testing console.

For more information on these parameters, refer to the Error Handler Parameters section on this page.

Click Run to run the test.

Save the Function

Once you are satisfied with the custom error handler, click Save.

Authenticate a MongoDB Atlas User

Use your MongoDB Atlas Administration API Key to log in to the App Services CLI:

appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"

Pull Your App's Latest Configuration Files

Run the following command to get a local copy of your configuration files:

appservices pull --remote=<App ID>

By default, the command pulls files into the current working directory. You can specify a directory path with the optional --local flag.

Write the Error Handler

Follow the steps in Define a Function to write your error handler source code and configuration file.

See the following template error handler as an example:

exports = async function(error, changeEvent) {
   // This sample function will log additional details if the error is not
   // a DOCUMENT_TOO_LARGE error
   if (error.code === 'DOCUMENT_TOO_LARGE') {
      console.log('Document too large error');
      // Comment out the line below in order to skip this event and not suspend the Trigger
      throw new Error('Encountered error: ${error.code}');
   }
   console.log('Error sending event to EventBridge');
   console.log('DB: ${changeEvent.ns.db}');
   console.log('Collection: ${changeEvent.ns.coll}');
   console.log('Operation type: ${changeEvent.operationType}');
   // Throw an error in your Function to suspend the Trigger
   // and stop processing additional events
   throw new Error('Encountered error: ${error.message}');
};

For more information on creating Functions, see Functions.

Add the Error Handler to Your Trigger Configuration

Add an error_handler attribute to your Trigger configuration file in the Triggers folder.

The Trigger configuration file should resemble the following:

      {
         "name": "...",
         "type": "DATABASE",
         "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>"
            }
         }
      }

For more information, see Trigger Configuration Files.

Deploy Your Changes

Run the following command to deploy your changes:

appservices push

Authenticate a MongoDB Atlas User

Call the Login endpoint with your MongoDB Atlas Administration API key pair:

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all App Services Admin API requests.

Create a Deployment Draft (Optional)

A draft represents a group of application changes that you can deploy or discard as a single unit. If you don't create a draft, updates automatically deploy individually.

To create a draft, send a POST request with no body to the Create a Deployment Draft endpoint:

curl -X POST 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

Create the Error Handler Function

Create the Function to handle errors for a failed AWS EventBridge Trigger via a POST request to the Create a new Function endpoint.

curl -X POST \
   https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/functions \
   -H 'Authorization: Bearer <access_token>' \
   -d '{
         "name": "string",
         "private": true,
         "source": "string",
         "run_as_system": true
      }'

Create the AWS EventBridge Trigger

Create the AWS EventBridge Trigger with error handling enabled via a POST request to the Create a Trigger endpoint.

curl -X POST \
   https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/triggers \
   -H 'Authorization: Bearer <access_token>' \
   -d '{
         "name": "string",
         "type": "DATABASE",
         "config": {
            "service_id": "string",
            "database": "string",
            "collection": "string",
            "operation_types": {
               "string"
            },
            "match": ,
            "full_document": false,
            "full_document_before_change": false,
            "unordered": true
         },
         "event_processors": {
            "AWS_EVENTBRIDGE": {
               "account_id": "string",
               "region": "string",
               "extended_json_enabled": false
            },
         },
         "error_handler": {
            "enabled": true,
            "function_id": "string"
         }
      }'

Deploy Your Changes

If you created a draft, you can deploy all changes in the draft by sending a POST request with no body to the Deploy a deployment draft endpoint.

If you did not create a draft as a first step, the individual Function and Trigger requests deploy automatically.

curl -X POST \
'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \