MongoDB (Beta)

You can configure MongoDB only as a target.

You must define at least one Micro-Integration Flow that specifies:

For a listing of available message headers, see MongoDB Message Headers.

Prerequisites

Before you configure the MongoDB Micro-Integration, ensure you meet these requirements:

  • The target MongoDB database and collection must already exist. This Micro-Integration does not automatically create databases or collections.

  • The database user specified in the connection configuration must have the necessary privileges to perform write operations on the target collection.

  • Message payloads must be JSON objects (or a single-element JSON array). The Micro-Integration converts the payload to a MongoDB document before writing.

  • If you want the Micro-Integration to update existing documents in UPSERT mode (the default), ensure each message payload includes an _id field that matches the target document. If the payload does not include an _id field, MongoDB generates a new unique _id and always inserts a new document. In INSERT mode, the Micro-Integration always inserts a new document regardless of whether the payload contains an _id field; if it does not, MongoDB generates one automatically.

MongoDB Connection Parameters

The following table describes the connection parameters for MongoDB.

Field Description
Connection String The MongoDB connection URI (for example, mongodb://host:27017).
Database Name The default MongoDB database name, using the database.collection format. You can override the database name for each Flow using the Destination setting.
Authentication

The authentication scheme to use when connecting to MongoDB. One of:

  • Basic Authentication—Authenticates using a username and password. For more information, see Basic Authentication.

  • TLS Authentication—Authenticates using a username and password over a TLS-encrypted connection. Requires trust store configuration and optionally supports mutual TLS via a key store. For more information, see TLS Authentication.

Basic Authentication

The following table describes the parameters for Basic Authentication.

Field Description
Username The user to authenticate with the MongoDB database.
Password The password to authenticate with the MongoDB database.
Auth Database The MongoDB database where the user is defined. The default is admin.

TLS Authentication

The following table describes the parameters for TLS Authentication.

Field Description
Username The user to authenticate with the MongoDB database.
Password The password to authenticate with the MongoDB database.
Auth Database The MongoDB database where the user is defined. The default is admin.
Trust Store The PKCS12 trust store file containing the CA certificate used to validate the MongoDB server.
Trust Store Password The password for the PKCS12 trust store.
Key Store The PKCS12 key store file containing the client certificate and private key for mutual TLS.
Key Store Password The password for the PKCS12 key store.

Micro-Integration Flow Parameters

You must configure the endpoint parameters for each Flow. Each Flow can have different settings, but they all share the connection details of the parent Micro-Integration.

MongoDB Target Parameters

The following table describes the parameters for configuring MongoDB as a target.

Setting a Smart Topic Destination on the Mappings step overrides the target destination field set on the Details step.

Field Description
Destination The target MongoDB collection in database.collection format. Overrides the Database Name connection parameter for this Flow.
Operation Mode The write behavior for the collection. UPSERT inserts a new document or updates an existing document with the same _id. INSERT always inserts a new document. The default is UPSERT.

Supported Payload Types

The MongoDB Micro-Integration accepts the following payload types. The Micro-Integration internally converts all payload types to documents before writing them to MongoDB.

Payload Type Description
Map A Map<String, Object> payload. All map keys must be of type String.
List A List containing exactly one element. Empty lists or lists with more than one element are not supported and cause the message to be rejected.
JSON String A JSON object or single-element JSON array encoded as a String. Maximum size: 2 MB.
JSON Bytes A JSON object or single-element JSON array encoded as a UTF-8 byte[]. Maximum size: 2 MB.

If a field in the payload is null or absent, that field is not included in the UPSERT operation.

Troubleshooting

The following troubleshooting tips might help you to resolve issues with this Micro-Integration. If problems persist, contact Solace.

Connection Failures

If the Micro-Integration cannot connect to MongoDB:

  • Verify that the connection string is a valid MongoDB URI (for example, mongodb://host:27017) and that the host and port are reachable from the environment where the Micro-Integration is running.

  • Check that no firewall rules are blocking outbound connections to the MongoDB host on the configured port.

  • If connecting to a replica set or sharded cluster, confirm that all hostnames in the connection string are resolvable from the Micro-Integration host.

Authentication Errors

If the Micro-Integration logs an authentication error or fails to connect with an authorization failure:

  • Verify that the username and password are correct for the configured authentication database.

  • Check that the Auth Database value in the connection configuration matches the database where the user account is defined. The default is admin.

  • Confirm that the user has write permissions on the target collection's database.

TLS Connection Errors

If the Micro-Integration logs TLS handshake failures or certificate errors when using TLS Authentication:

  • Verify that the trust store file uploaded to the connection configuration is a valid PKCS12 file containing the CA certificate that signed the MongoDB server's certificate.

  • Confirm that the trust store password is correct.

  • If using mutual TLS, verify that the key store file contains a valid client certificate and private key, and that the key store password is correct.

  • Check that the server certificate has not expired. If it has, replace it and update the trust store.

Collection Not Found or Destination Format Errors

If the Micro-Integration logs errors about an invalid or missing collection:

  • Verify that the Destination field in the flow configuration uses database.collection format (for example, mydb.events). Both the database name and collection name are required.

  • Confirm that the database and collection exist in MongoDB. The Micro-Integration does not create databases or collections automatically.

  • If using the scst_targetDestination header for dynamic routing, verify that the header value is also in database.collection format.

Unsupported Payload Type Errors

If the Micro-Integration rejects messages with an IllegalArgumentException or an unsupported payload error:

  • Verify that the message payload is one of the supported types: a Map<String, Object>, a single-element List, a JSON object or single-element JSON array as a String, or a JSON object or single-element JSON array as a UTF-8 byte[].

  • If the payload is a List, check that it contains exactly one element. Empty lists and lists with more than one element are not supported.

  • If the payload is a Map, confirm that all map keys are of type String.

Payload Too Large Errors

If the Micro-Integration rejects messages due to payload size:

  • Check that JSON String and JSON Bytes payloads do not exceed 2 MB. Messages larger than this limit are not supported.

  • If large payloads are expected, consider splitting the data into smaller messages before publishing to the event broker.