MongoDB v4+

8 min

The MongoDB v4+ integration enables Manufacturing Connect Edge (MCe) to connect with a MongoDB cluster, standalone server, or Atlas-hosted deployment. The connector writes data from Message Broker into a target collection and also supports ad hoc queries from the Analytics IT Hub processor.

Supported communication

Outbound (Publish data from MCe to MongoDB): Yes

Inbound (Subscribe data from MongoDB to MCe): No

Analytics IT Hub processor support: Yes

Configurations

Field	Details	Required
Name	Connector name.	Yes
Connection scheme	Connection string scheme. mongodb connects to a single host on the given port. mongodb+srv resolves replica-set members through DNS SRV records (used by MongoDB Atlas) and enables TLS by default; the Port field is ignored.	Yes
Hostname	DNS name or IP of the host. For mongodb+srv, this is the SRV record name, for example cluster0.mongodb.net.	Yes
Port	Port of MongoDB host. Ignored when the scheme is mongodb+srv.	No
SSL Mode	TLS/SSL connection mode. disable: no TLS. require: TLS without certificate validation. verify-ca: verify the server certificate against the CA. verify-full: verify the CA and hostname.	No
CA Certificate	Add a CA certificate here, or add it to the system-wide certificate list.	No
Certificate	Client certificate for mutual TLS authentication with MongoDB. Paste the PEM-encoded certificate here.	No
Private key	Private key corresponding to the client certificate. Must match the certificate provided above.	No
Username	User name.	No
Password	User password.	No
Database	Database name.	Yes
Auth database	Authentication database (authSource). Set this to the data database name if the user was created inside the target database.	No
Auth mechanism	Authentication mechanism. DEFAULT lets the driver negotiate the standard username and password mechanism (SCRAM-SHA-256 on MongoDB 4.0+, falling back to SCRAM-SHA-1). Use PLAIN for LDAP passthrough or MONGODB-X509 for TLS client certificate authentication.	No
Collection	Target collection to write data into. Must exist in the selected database unless Create collection is enabled.	Yes
Mapping	Key-value pairs mapping incoming message field names to MongoDB document field names. Leave empty to use source field names as-is. Prefix a value with @ for a static literal. When Enable JSONPath is on, a value starting with $ is read as a JSONPath expression instead of a message key.	No
Enable JSONPath	Read mapping values that start with $ as JSONPath expressions, so a document field can be filled from a nested payload field such as $.factory.line.machine.sensors.temperature. Dotted paths, quoted keys, and array indexes are supported; an expression that points at an object or array stores it as a nested document. Values that do not start with $ keep their usual meaning, and an expression matching nothing writes null.	No
Create collection	Create the collection if it doesn't exist. Requires the appropriate database permissions.	Yes
Commit timeout	Transaction commit timeout (ms).	No
Batch timeout	The maximum time (in milliseconds) to wait after the previous insert attempt before writing an incomplete batch to the database.	No
Max transaction size	Maximum number of messages before a transaction is committed regardless of timeout.	No
Bulk insert count	Buffer messages and perform bulk insert once the Bulk insert count value is reached.	No
Write mode	How the connector acknowledges messages. sync: a message is acknowledged only after its batch is inserted, so with persistent storage on, a failed write is kept and retried. async: a message is acknowledged once buffered, for higher throughput, and a batch that fails to write is dropped. Default: sync.	No
Parallel transactions	The maximum number of batch inserts that run at the same time, each on its own database connection. Values above 1 increase throughput, but documents from different batches can be written out of publish order. Default: 1.	No
Parallel Publish Count	The number of simultaneously publishing messages.	No
Throttling limit	Set a limit on the number of outbound messages per second. If sending data to a server that has restrictions on the rate of incoming messages, this ensures that no messages are lost.	No

Persistent storage configurations

Field	Details	Required
Persistent storage	If enabled, messages in the outbound queue are stored on disk. If there are interruptions in connection or power loss, messages are retained and sent when the connection is restored.	No
Persistent storage size limit	Set the size limit for storing persisted data in GB.	No
Queue Mode	Select the sequence of data transfer: FIFO or LIFO. FIFO (First In First Out) sends the earliest message first. LIFO (Last In First Out) sends the latest message first.	No

SSL Mode behavior

Value	Behavior
disable	No TLS (standard mongodb:// scheme only). Connection is plaintext. Certificate fields are ignored.
require	TLS is used, but the server certificate isn't verified (driver flag tlsInsecure=true). A supplied CA Certificate isn't used in this mode. To have the CA checked, use verify-ca or verify-full.
verify-ca	The server certificate chain is verified against the supplied CA Certificate (or the OS trust store if none is supplied). The certificate hostname isn't checked (driver flag tlsAllowInvalidHostnames=true).
verify-full	The server certificate chain is verified, and the hostname on the certificate must match the Hostname field. Recommended for production.

Authentication

The connector supports three authentication paths and doesn't enforce any of them when you save the configuration. Whether a connection succeeds depends on the authentication policy of the MongoDB server.

Mode	Config	Notes
Username / password	Set Username (and typically Password). Auth mechanism = DEFAULT, SCRAM-SHA-256, SCRAM-SHA-1, or PLAIN	Standard path. DEFAULT lets the driver negotiate SCRAM-SHA-256 (MongoDB 4.0+) or SCRAM-SHA-1. PLAIN (LDAP passthrough) sends credentials in cleartext during the SASL exchange, and the connector logs a warning when it connects if SSL Mode is disable. In production, use verify-ca or verify-full.
Client certificate (X.509)	Auth mechanism = MONGODB-X509. Provide Certificate and Private key. SSL Mode must not be disable. This is mandatory: the mongodb+srv scheme alone isn't enough (see SSL Mode behavior above)	The user identity is the Subject DN of the certificate. Saving the configuration fails if SSL Mode is disable or not set (the default is disable), because the connector would then pass no client certificate to the driver, even if mongodb+srv forced TLS at the socket layer.
Anonymous	Leave both Username and Password empty. Auth mechanism = DEFAULT. No client certificate	The connector opens the connection without sending credentials. Saving a password with no username fails, because the connection would otherwise open anonymously and silently drop the password. The MongoDB server must allow unauthenticated access, that is, be started without --auth or security.authorization: enabled, or have an anonymous role granted. Production Atlas and any deployment with authentication enabled reject the first operation.

JSONPath expressions

Off by default. With it off, every mapping value keeps its usual meaning and nothing about an existing configuration changes. With it on, a mapping value starting with $ is evaluated against the published payload, so a document field can be filled from a nested field. Values that do not start with $ still resolve as before: a message key, or an @ literal.

Given this payload:

{
  "factory": {
    "line": {
      "product": "Engine Block",
      "machine": {
        "status": "running",
        "sensors": { "temperature": 72.4 }
      }
    }
  }
}

Field	Mapping value	Stored
product	$.factory.line.product	Engine Block
status	$.factory.line.machine.status	running
sensor_temperature	$.factory.line.machine.sensors.temperature	72.4
site	@plant-a	plant-a

Query with the Analytics IT Hub processor

Because this connector supports the Analytics IT Hub processor, an Analytics flow can use the processor to run ad hoc MongoDB commands against it. Trigger the processor with a message that names the connector instance and carries the command in body. Use a cursor-returning command such as find, given as a JSON string. Only connector and body are required. The other fields are optional and carry the defaults shown here, so the whole message can be copied and edited as needed.

{
  "connector": "<mongodb-connector-id>",
  "body": "{ \"find\": \"readings\", \"filter\": { \"device_id\": \"press-01\" }, \"limit\": 100 }",
  "headers": {},
  "response_topic": "cc.results.mongodb",
  "force_reset_cache": false,
  "stream_name": "",
  "message_id_prefix": ""
}

The connector runs the command and publishes each result document to the response_topic, one message per document. The IT Hub processor subscribes to that topic and forwards each message to its output, carrying the documents on to the rest of the Analytics flow. For a read that returns documents, the resulting data can also be shown in the processor's tabular view.

The optional fields map to the processor's advanced parameters: headers passes free-form headers, force_reset_cache drops any cached connector state before the call, stream_name verifies the response topic maps to a JetStream stream, and message_id_prefix seeds the per-chunk message IDs.

MongoDB Integration Guide

Add a Connector

Manage Connectors