MongoDB
Collection MONGODB and Delivery MONGODB_WRITE.
A single External Connection covers four services: self-hosted MongoDB, MongoDB Atlas, Azure Cosmos DB (Mongo API) and AWS DocumentDB. These are not different protocols — same driver, same wire conversation; what changes are defaults and validations, and that is what the Service field carries.
| Service | What it changes in the connection |
|---|---|
| MongoDB (self-hosted) | No restrictions. The only one where the Replica set field applies |
| MongoDB Atlas | Requires a mongodb+srv:// URI and TLS. A network failure turns into a hint about the project’s IP Access List |
| Azure Cosmos DB (Mongo API) | TLS required and retryable writes off — the service does not implement the feature |
| AWS DocumentDB | TLS required, retryable writes off, and Amazon’s CA certificate in the certificate field |
Connection
| Field | What it is for |
|---|---|
| Service | Sets the defaults above. Picking the wrong one usually shows up as a handshake rejection, with no explanation |
| Connection URI | Address only: mongodb://mongo:27017 or mongodb+srv://cluster0.abcde.mongodb.net. No username or password |
| Database | Default database for the connection |
| Test collection | Optional. When set, Keep Alive also proves the collection answers reads |
| Username / Password | Access credentials. The password is encrypted at rest and never returns to the screen |
| Authentication database | The authSource — where the user was created. admin in most installations |
| Replica set | Self-hosted only, when connecting straight to the nodes |
| Timeout (ms) | Applies to all three driver limits: server selection, connection and operation |
| Connect using TLS | Already on for managed services, where TLS is mandatory |
| Validate TLS certificate / CA certificate | Same semantics as the other connections. The CA is needed with an internal CA — and on DocumentDB, which requires Amazon’s certificate |
| Retry writes after network failure | Retryable writes. Self-hosted only: Cosmos DB and DocumentDB do not support it, and the connection is made with the feature off |
The URI does not accept embedded credentials (mongodb://user:password@host). The URI is shown
in the External Connections list and in configuration export files — a password there would leak in
both places. The CMS rejects such a URI and asks for the credentials in their own fields, where they
are encrypted.
Because credentials live outside the URI, a password containing @, : or / works without
escaping. That is the opposite of tools requiring the whole connection string, where this detail is
a classic cause of an unexplained “authentication failed”.
Test Connection
The test runs in three stages, each failing for a different reason:
- Ping — validates URI, TLS, route and credentials at once. This is the stage that separates “could not reach the server” from “the server rejected the credentials”.
- Listing the database collections — proves the configured database exists and is reachable by
this user, which the ping does not tell (the ping runs against
admin). - Test collection — when set, proves reads actually work.
The result carries the version reported by the server. On Cosmos DB and DocumentDB that number is the protocol version they emulate, not a real MongoDB — and that is exactly the useful information, since it determines which features will work.
Keep Alive
Point the Application at the External Connection and pick the MongoDB Keep Alive type. Each cycle repeats the test above. With Test collection filled in, the cycle uses the estimated document count — which reads metadata instead of scanning the collection, so it does not weigh on the customer’s database.
Collection
The Collection reads the collection on the scheduled interval and turns each document into a message, with the same Result Mode as SQL Collections (all documents in one payload, or one message per document).
| Field | What it is for |
|---|---|
| Operation | find (filter) or aggregate (pipeline). The pipeline is the way to go when data must be grouped, joined or reshaped on the server |
| Collection | Collection being read |
| Filter / Pipeline | JSON — the find filter or the aggregate stage array |
| Projection / Sort | JSON, find only ({"tag": 1} / {"dataEvento": -1}). In a pipeline, $project and $sort play that role |
| Document limit | Per-run ceiling. It exists so a badly written filter cannot pull the whole collection into memory |
| Payload format | Simple converts ObjectId and Decimal128 to text and Date to ISO 8601 — what the Transformer and the destination expect. EJSON keeps the exact type of every value |
| Post-collection command | Update applied to the documents read, in JSON |
There is no database field on the Collection or the Delivery: it always comes from the Application’s External Connection, as with PostgreSQL and SQL Server. To read or write across several databases of the same cluster, register one External Connection per database — that way Keep Alive keeps monitoring exactly the database the integration uses.
Incremental scanning
As with InfluxDB, the window comes from the query itself. {{ultimaExecucao}} marks where the
previous run stopped:
{ "dataEvento": { "$gt": { "$date": "{{ultimaExecucao}}" } } }The {"$date": ...} wrapper around the placeholder is not optional. Without it MongoDB compares
a date against a string — and the filter simply matches nothing, with no error at all. It is the
easiest mistake to make here.
On the first run, with no watermark yet, {{ultimaExecucao}} resolves to 1970-01-01: the first scan
brings everything the filter reaches, bounded by the Document limit.
Post-collection command
Unlike InfluxDB, “mark as read” exists here — a document has a stable _id. It is the standard
pattern for using a collection as an outbound queue:
{ "$set": { "processado": true } }The filter of that update is not configurable: the CMS always applies it to the _ids that run
actually read. A free-form filter could mark as processed a document the Collection never delivered
— including one that arrived between the read and the update, which would be lost unnoticed.
Input parameters and security
The Collection accepts Input Parameters (dynamic Collection API) and Variables inside the filter,
using {{alias}}. Substitution happens on the already structured value, never on the JSON text:
a producer sending {"$ne": null} in a parameter would see it become the literal string
{"$ne":null}, not an operator — the filter keeps looking for that value instead of returning the
whole collection.
A placeholder in a field name is rejected on save, for the same reason.
The CMS also rejects, in a Collection: $where, $function and $accumulator (they run JavaScript
on the MongoDB server), $out and $merge (they write from a query) and unknown aggregation stages.
$lookup, $graphLookup and $unionWith are allowed — they are reads.
Delivery
MONGODB_WRITE writes the message as a document. It is the simplest Delivery in the CMS, and by
design: the payload is already JSON and MongoDB stores JSON, so there is no field map to
configure — the document written is the Transformer output.
| Field | What it is for |
|---|---|
| Write mode | See the table below |
| Target collection | Where to write |
| Key fields | Only in modes that match an existing document: payload fields identifying the document, comma separated |
| Write timestamp field | Optional. Where the CMS stamps the write instant, as a real date |
| Content Template | Optional. Shapes the document before writing; empty writes the whole payload |
| Mode | What it does | When to use |
|---|---|---|
| Insert one document | Creates a new document | History, log, event — each message is its own fact |
| Insert batch | Creates N documents from an array | A Collection that emitted several rows in a single message |
| Update or create (upsert) | Matches by key; creates when missing | “Current state” of each asset/line |
| Update only | Matches by key; never creates | When the document must already exist — the message should not create records |
Batches are written with ordered: false: one rejected document (a duplicate key, say) does not stop
the rest. And the delivery return carries what actually happened at the destination (inserted,
matched, modified, created by upsert), visible on the message detail screen.
Common errors
| Symptom | Likely cause | Fix |
|---|---|---|
| “No node answered within the time limit” on Atlas | The CMS server IP is not in the project’s Network Access | Allow the IP in Atlas. Credentials have nothing to do with it |
| “MongoDB rejected the credentials” with correct username and password | Wrong authSource — the user exists in a specific database, not in admin | Adjust Authentication database |
| Connection refused right away on DocumentDB | Retryable writes — the service does not implement it | Pick AWS DocumentDB in the service list; the CMS turns the feature off by itself |
| TLS certificate error | Internal CA, or Amazon’s certificate missing on DocumentDB | Paste the certificate in the CA certificate field |
| “Collection does not exist in database” | Wrong collection name, or wrong database | The test tells this apart from missing permission on purpose — check both fields |
| The Collection returns nothing, with no error | Missing {"$date": ...} around {{ultimaExecucao}} | Wrap the placeholder, as shown under incremental scanning |
| “The payload for a MongoDB Delivery must be a JSON object” | The Transformer returned text, a number or an array of scalars | Fix the Transformer, or use the Content Template to build the document |
| “Upsert key field(s) missing a value” | The message did not carry one of the key fields | Nothing was written, on purpose — fix the source or the Transformer |