MongoDB Connector Reference

This documentation provides a reference guide for the MongoDB Connector.

Connection configurations

The MongoDB connector can be used to deal with two types of connections:

• Connection String URI (URI): Directly provide a MongoDB connection string URI.

• Connection Parameters: Configure the connection with individual parameters

  • Standard: Standard MongoDB connection parameters
  • DNS Seed List: MongoDB connection using DNS SRV records for server discovery. (DNS SRV Lookup)

The supported connection URI types and connection options are listed in the MongoDB Connection String documentation.

Parameter Name	Type	Description	Default Value	Required
Connection Name	String	A unique name to identify the connection.	-	Yes
Type	String	Method to construct the connection URI Possible values: Connection String URI: Directly provide a MongoDB connection string URI. Connection Parameters: Configure the connection with individual parameters	Connection String URI	Yes
Connection String URI Configuration
Connection String URI	String	The MongoDB connection string URI. This is only applicable for the connection type "Connection String URI". Eg: [prefix]://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]	-	No
Database	String	The name of the database in the MongoDB server.	-	Yes
Connection Parameters Configuration
Use DNS SRV Lookup	String	When true, the driver uses DNS SRV records to discover the MongoDB server. This is only applicable for the connection type "Connection Parameters".	false	No
Host	String	The name of the host. It identifies either a hostname, IP address, or unix domain socket.	-	No
Port	Number	The port number. This is only applicable for the connection type "Connection Parameters" and you are not using DNS SRV Lookup.	-	No
Database	String	The name of the database in the MongoDB server.	-	Yes
Seed List	String	A seed list is used by drivers and clients (like the mongo shell) for initial discovery of the replica set configuration. Seed lists can be provided as host:port pairs. This is used in replica sets and shared clusters. This is only applicable for the connection type "Connection Parameters" and you are not using DNS SRV Lookup.	-	No
Username	String	The user name to authenticate the database associated with the user.	-	No
Password	String	The password to authenticate the database associated with the user.	-	No
Replica Set	String	The name of the replica set to connect to.	-	No
Auth Source	String	The database name associated with the user's credentials.	-	No
Auth Mechanism	String	The authentication mechanism to use.	-	No
Auth Mechanism Properties	String	The authentication mechanism properties.	-	No
Gssapi Service Name	String	The Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances to which you are connecting.	-	No
Write Concern W Option	String	Corresponds to the write concern w Option.	-	No
Write Concern Timeout MS	Number	The time limit (in milliseconds) of the write concern.	-	No
Journal	String	When this option used, the Micro Integrator requests an acknowledgement from MongoDB that the write operation has been written to the journal. This applies when the write concern is set to 'j'.	-	No
Maximum Pool Size	Number	The maximum number of connections in the connection pool.	100	No
Minimum Pool Size	Number	The minimum number of connections in the connection pool.	0	No
Maximum Idle Time MS	Number	The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed.	-	No
Wait Queue Multiple	Number	The maximum pool size is multiplied by this value to calculate the maximum number of threads that are allowed to wait for a connection to become available in the pool.	-	No
Wait Queue Timeout MS	Number	The maximum time in milliseconds that a thread can wait for a connection to become available.	-	No
SSL	Boolean	A boolean to enable or disables TLS/SSL for the connection.	-	No
SSL Invalid Host Names Allowed	Boolean	User name used to connect with the file server.	-	No
Connect Timeout TS	Number	The time in milliseconds for attempting a connection before timing out. For most drivers, the default is to never timeout.	-	No
Socket Timeout MS	Number	The time in milliseconds for attempting a send or receive on a socket before the attempt times out. For most drivers, the default is to never timeout.	-	No
Compressors	String	Comma-delimited string of compressors to enable network compression for communication between this client and a mongod/mongos instance.	-	No
Zlib Compression Level	Number	An integer that specifies the compression level when zlib is used for network compression.	-	No
Read Concern Level	String	The level of isolation.	-	No
Read Preference	String	Specifies the read preferences for this connection.	-	No
Maximum Staleness Seconds	Number	The maximum time (in seconds) a connection can remain stale before the client stops using it for read operations.	-	No
Read Preference Tags	String	Document tags as a comma-separated list or colon-separated key-value pairs.	-	No
Local Threshold MS	Number	The latency (in milliseconds) that is allowed when selecting a suitable MongoDB instance from the list of available instances.	15	No
Server Selection Timeout MS	Number	The time (in milliseconds) that is allowed for server selection before an exception is thrown.	30,000	No
Server Selection Try Once	Boolean	When true, the driver scans the MongoDB deployment exactly once after server selection fails and then either selects a server or raises an error. When false, the driver searches for a server until the serverSelectionTimeoutMS value is reached. Only applies for single-threaded drivers.	true	No
Heartbeat Frequency MS	Number	Controls the intervals between which the driver checks the state of the MongoDB deployment. The interval (in milliseconds) between checks, counted from the end of the previous check until the beginning of the next one.	-	No
App Name	String	Specify a custom app name.	-	No
Retry Reads	Boolean	Enables retryable reads.	-	No
Retry Writes	Boolean	Enable retryable writes.	-	No
UUID Representation	String	The type of UUID representation.	-	No

Sample Configuration of Connection URI

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="uriConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>uriConnection</name>
        <connectionType>MONGODB</connectionType>
        <inputType>Connection String URI</connectionType>
        <connectionURI>mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB</connectionURI>
        <database>users</database>
    </mongodb.init>
</localEntry>

Sample configuration of Connection parameters configs

Sample configuration of STANDARD (standalone) configs.

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="standaloneStandardConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>standaloneStandardConnection</name>
        <connectionType>MONGODB</connectionType>
        <inputType>Connection Parameters</inputType>
        <useDnsSrvLookup>false</useDnsSrvLookup>
        <database>users</database>
        <host>localhost</host>
        <port>27017</port>
        <username>administrator</username>
        <password>1234</password>
    </mongodb.init>
</localEntry>

Sample configuration of Connection parameters (replica set) configs

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="replicaSetStandardConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>replicaSetStandardConnection</name>
        <connectionType>MONGODB</connectionType>
        <inputType>Connection Parameters</inputType>
        <useDnsSrvLookup>false</useDnsSrvLookup>
        <seedList>mongodb1.example.com:27317,mongodb2.example.com:27017</seedList>
        <database>users</database>
        <username>administrator</username>
        <password>1234</password>
        <authSource>aDifferentAuthDB</authSource>
        <ssl>true</ssl>
        <w>majority</w>
        <replicaSet>mySet</replicaSet>
        <retryWrites>true</retryWrites>
    </mongodb.init>
</localEntry>

Sample Configuration of Connection parameters (with DNS SRV lookup) configs

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="dslConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>dslConnection</name>
        <connectionType>MONGODB</connectionType>
        <inputType>Connection Parameters</inputType>
        <useDnsSrvLookup>true</useDnsSrvLookup>
        <host>server.example.com</host>
        <database>users</database>
        <username>administrator</username>
        <password>1234</password>
        <authSource>aDifferentAuthDB</authSource>
        <retryWrites>true</retryWrites>
        <w>majority</w>
    </mongodb.init>
</localEntry>

Operations

The following operations allow you to work with the MongoDB connector. Click an operation name to see parameter details and samples on how to use it.

insertOne

Inserts a document into a collection. See the related insertOne documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Document	JSON String	A document to insert into the collection.	-	Yes
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.insertOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <document>{json-eval($.document)}</document>
</mongodb.insertOne>

Sample Request

{
    "collection": "TestCollection",
    "document": {
        "_id": "123",
        "name": "John Doe"
    }
}

insertMany

Inserts multiple documents into a collection. See the related insertMany documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Documents	JSON String	An array of documents to insert into the collection.	-	Yes
Ordered	Boolean	A boolean specifying whether the MongoDB instance should perform an ordered or unordered insert.	true	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.insertMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <documents>{json-eval($.documents)}</documents>
    <ordered>True</ordered>
</mongodb.insertMany>

Sample Request

{
    "collection": "TestCollection",
    "documents": [
        {
            "name": "Jane Doe",
            "_id": "123"
        },
        {
            "name": "Jane Doe",
            "_id": "1234"
        },
        {
            "name": "Jane Doe",
            "_id": "12345"
        }
    ]
}

findOne

Returns one document that satisfies the specified query criteria on the collection. If multiple documents satisfy the query, this method returns the first document according to the natural order. See the related find documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	Specifies query selection criteria using query operators. To return the first document in a collection, omit this parameter or pass an empty document ({}).	{}	No
Projection	JSON String	Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.	-	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.findOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <responseVariable>mongodb_findOne_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.findOne>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "name": "Jane Doe"
    }
}

find

Selects documents in a collection or view and returns a cursor to the selected documents. See the related find documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	Selection filter using query operators. To return all documents in a collection, omit this parameter or pass an empty document ({}).	{}	No
Projection	JSON String	Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.	-	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Sort	JSON String	A document that defines the sort order of the result set.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.find configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <responseVariable>mongodb_find_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.find>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "name": "John Doe"
    }
}

updateOne

Updates a single document within the collection based on the filter. See the related updateOne documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	The selection criteria for the update. The same query selectors as in the find() method are available. Specify an empty document {} to update the first document returned in the collection.	{}	No
Update	JSON String	The modifications to apply.	-	Yes
Upsert	Boolean	Creates a new document if no documents match the filter.	false	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Array Filters	JSON String	An array of filter documents that determine which array elements to modify for an update operation on an array field.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Info

Array Filters parameter should be in a JSON object format. See the example given below.

{
    "collection": "TestCollection",
    "query": {
        "grades": {
            "$gte": 100
        }
    },
    "update": {
        "$set": {
            "grades.$[element]": 100
        }
    },
    "arrayFilters": {
        "element": {
            "$gte": 100
        }
    }
}

Sample Configuration

<mongodb.updateOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <update>{json-eval($.update)}</update>
    <upsert>False</upsert>
    <responseVariable>mongodb_updateOne_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.updateOne>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "_id": "123"
    },
    "update": {
        "$set": {
            "name": "Jane Doe"
        }
    }
}

updateMany

Updates all documents that match the specified filter for a collection. See the related updateMany documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	The selection criteria for the update. The same query selectors as in the find() method are available. Specify an empty document {} to update all documents in the collection.	{}	No
Update	JSON String	The modifications to apply.	-	Yes
Upsert	Boolean	Creates a new document if no documents match the filter.	false	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Array Filters	JSON String	An array of filter documents that determine which array elements to modify for an update operation on an array field.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Info

Array filters parameter should be in a JSON object format. See the example given below.

{
    "collection": "TestCollection",
    "query": {
        "grades": {
            "$gte": 100
        }
    },
    "update": {
        "$set": {
            "grades.$[element]": 100
        }
    },
    "arrayFilters": {
        "element": {
            "$gte": 100
        }
    }
}

Sample Configuration

<mongodb.updateMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <update>{json-eval($.update)}</update>
    <upsert>False</upsert>
    <responseVariable>mongodb_updateMany_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.updateMany>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "_id": "123"
    },
    "update": {
        "$set": {
            "name": "Jane Doe"
        }
    }
}

deleteOne

Removes a single document from a collection. See the related deleteOne documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	Specifies deletion criteria using query operators. Specify an empty document {} to delete the first document returned in the collection.	{}	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.deleteOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <responseVariable>mongodb_deleteOne_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.deleteOne>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "name": "Jane Doe"
    }
}

deleteMany

Removes all documents that match the query from a collection. See the related deleteMany documentation for more information.

Parameter Name	Type	Description	Default Value	Required
Collection	String	The name of the MongoDB collection.	-	Yes
Query	JSON String	Specifies deletion criteria using query operators. To delete all documents in a collection, pass in an empty document ({}).	{}	No
Collation	JSON String	Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks.	-	No
Output Variable Name	responseVariable	Name of the variable to which the output of the operation should be assigned	-	Yes
Overwrite Message Body	overwriteBody	Replace the Message Body in Message Context with the output of the operation (This will remove the payload from the above variable).	false	Yes

Sample Configuration

<mongodb.deleteMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <responseVariable>mongodb_deleteMany_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</mongodb.deleteMany>

Sample Request

{
    "collection": "TestCollection",
    "query": {
        "name": "John Doe"
    }
}