When to Use
- E-commerce order capture: When a customer completes checkout, immediately insert a new order document into the
orders collection. Include line items, shipping address, payment reference, and initial status in a single atomic write. Downstream nodes can reference the returned insertedIds[0] to link fulfilment tasks.
- IoT sensor data ingestion: A scheduled trigger collects a batch of sensor readings from edge devices. Insert all readings in one operation using an array of documents, one per sensor per interval. Set
Ordered: false so that a malformed reading from one sensor does not block the remaining batch.
- HR employee onboarding: When a new hire record is created in the HRIS system via webhook, insert a corresponding employee profile document into MongoDB with department, role, start date, and initial permissions. The returned ID is stored as a variable for subsequent workflow steps that provision access.
- SaaS audit log persistence: Insert structured audit log entries for every user action in a multi-tenant SaaS application. Each document includes
tenantId, userId, action, resourceType, resourceId, and timestamp. Querying and aggregating these logs later supports compliance reporting.
- Analytics event recording: After a workflow processes a business event (payment received, subscription upgraded, support ticket resolved), insert a structured event document into a time-series collection. These events feed aggregation pipelines for dashboards and KPI tracking without requiring a dedicated analytics database.
Configuration
Connection
| Field | Required | Description |
|---|
ConnectionUri | Required | MongoDB connection string. Example: mongodb+srv://appuser:s3cr3t@cluster0.abc12.mongodb.net/. Always reference a stored credential: {{ $credentials.mongodbAtlas }}. |
Database | Required | The database name to write into. Example: ecommerce, hrcore, analytics. |
Collection | Required | The collection name. Example: orders, employees, audit_logs. Created automatically if it does not exist. |
Operation
| Field | Required | Description |
|---|
Documents | Required | Array of document objects to insert. Each element is a plain JSON object representing one document. Minimum one document required. Example: [{"orderId":"ORD-001","customerId":"C-42","total":149.99}]. Supports expressions: {{ $json.documentsArray }}. |
Ordered | Optional | Default true. When true, MongoDB stops inserting on the first error and reports the failure. When false, MongoDB continues inserting remaining documents despite individual failures — ideal for bulk ingestion where partial success is acceptable. Use false for parallel or idempotent batch inserts. |
Sample Configuration
Bulk insert of customer order records from a webhook payload containing an array of new orders:
{
"resource": "document",
"operation": "insert",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "ecommerce",
"Collection": "orders",
"Documents": [
{
"orderId": "ORD-2024-001847",
"customerId": "CUST-10293",
"customerEmail": "jane.doe@example.com",
"status": "pending",
"lineItems": [
{ "sku": "SHOE-BLK-42", "qty": 1, "unitPrice": 89.99 },
{ "sku": "SOCK-WHT-M", "qty": 3, "unitPrice": 9.99 }
],
"subtotal": 119.96,
"shippingCost": 5.95,
"total": 125.91,
"shippingAddress": {
"line1": "42 Elm Street",
"city": "Austin",
"state": "TX",
"zip": "78701"
},
"createdAt": "{{ $now }}",
"tenantId": "tenant_acme"
}
],
"Ordered": true
}
Validation Errors
| Error | Cause |
|---|
connectionUri is required | ConnectionUri is empty, null, or not provided. |
database is required | Database field is empty or whitespace. |
collection is required | Collection field is empty or whitespace. |
documents array cannot be empty | Documents is null, an empty array [], or not an array type. |
INSERT_FAILED | MongoDB rejected one or more documents — possible causes include a unique index violation (duplicate key), schema validation rule failure, or a document exceeding the 16 MB BSON size limit. |
Ordered vs unordered failure behaviour: With Ordered: true, insertion stops at the first error and the error port fires. With Ordered: false, all documents are attempted and insertedCount reflects only the successful ones — the success port still fires. Always check insertedCount against the input length when using unordered mode.
Output — Success Port
| Field | Type | Description |
|---|
insertedCount | integer | Number of documents successfully inserted. With Ordered: true this is either the full count or 0. With Ordered: false it may be less than the number of input documents if some failed. |
insertedIds | array | Array of MongoDB ObjectID strings assigned to each successfully inserted document, in the same order as the input Documents array. |
status | string | Always "success" on the success port. |
resource | string | Always "document". |
operation | string | Always "insert". |
Sample Output
{
"insertedCount": 2,
"insertedIds": [
"6651a3f2c4e8b9d0a1f23456",
"6651a3f2c4e8b9d0a1f23457"
],
"status": "success",
"resource": "document",
"operation": "insert"
}
Expression Reference
| Expression | Returns | Description |
|---|
{{ $output.InsertNode.insertedCount }} | integer | How many documents were inserted. Compare to input array length to detect partial failures in unordered mode. |
{{ $output.InsertNode.insertedIds }} | array | Full array of new document IDs. Pass to a Loop node to process each inserted record. |
{{ $output.InsertNode.insertedIds[0] }} | string | The ObjectID of the first inserted document. Use to link to the created record immediately downstream. |
{{ $output.InsertNode.insertedIds[0] | string }} | string | Explicit string cast of the first ID for use in downstream query filters or HTTP request bodies. |
{{ $output.InsertNode.status }} | string | Confirm "success" for conditional branching after the node. |
Node Policies & GuardRails
| Policy | Recommendation |
|---|
| Credential storage | Always store the MongoDB connection string in BizFirst Credentials Manager and reference it via {{ $credentials.credentialName }}. Never paste the raw URI containing a password directly into the ConnectionUri field. |
| Document size limit | MongoDB enforces a hard 16 MB per-document BSON limit. If inserting large documents (e.g. those with embedded binary content), validate sizes upstream or store large payloads in S3 and store a reference URL instead. |
| Idempotency for retries | If your workflow may retry on transient errors, use a natural unique key (e.g. orderId, externalRef) as a custom _id field and ensure a unique index exists on that field. An upsert via document/update is often safer than insert for retry-safe workflows. |
| Bulk insert ordering | Set Ordered: false for high-volume event ingestion pipelines where individual document failures should not block the batch. Set Ordered: true when documents have a logical dependency (e.g. inserting a parent before children in the same batch). |
| Multi-tenancy isolation | Always include a tenantId field in every document for multi-tenant applications. Define an index on tenantId and enforce it in all downstream queries so tenant data cannot leak across boundaries. |
| Schema validation | Configure MongoDB collection-level schema validation rules ($jsonSchema) to reject malformed documents at the database layer rather than relying solely on workflow-level validation. This provides defence-in-depth for direct database writes from other sources. |
| Index on write-heavy fields | If downstream workflows frequently query by status, customerId, createdAt, or tenantId, ensure compound indexes exist before inserting large volumes. Inserting millions of documents without indexes causes subsequent find operations to scan the full collection. |
| Error port handling | Always connect the error port to a notification or logging node. Unhandled insert failures silently drop data in automated pipelines. |
Workflow Examples
Example 1 — Single Order Insert on Checkout Webhook
{
"resource": "document",
"operation": "insert",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "ecommerce",
"Collection": "orders",
"Documents": [
{
"orderId": "{{ $json.orderId }}",
"customerId": "{{ $json.customerId }}",
"status": "pending",
"total": "{{ $json.cartTotal }}",
"currency": "USD",
"items": "{{ $json.cartItems }}",
"createdAt": "{{ $now }}",
"tenantId": "{{ $json.tenantId }}"
}
],
"Ordered": true
}
Example 2 — Bulk Sensor Data Insert (Unordered)
{
"resource": "document",
"operation": "insert",
"ConnectionUri": "{{ $credentials.mongodbIoT }}",
"Database": "iot_platform",
"Collection": "sensor_readings",
"Documents": "{{ $json.readings }}",
"Ordered": false
}
Where $json.readings is an array such as:
[
{ "sensorId": "TEMP-001", "value": 22.4, "unit": "C", "recordedAt": "2024-11-15T08:00:00Z", "siteId": "PLANT-A" },
{ "sensorId": "TEMP-002", "value": 23.1, "unit": "C", "recordedAt": "2024-11-15T08:00:00Z", "siteId": "PLANT-A" },
{ "sensorId": "HUM-001", "value": 58.2, "unit": "%", "recordedAt": "2024-11-15T08:00:00Z", "siteId": "PLANT-A" }
]
Example 3 — Audit Log Entry After Approval Decision
{
"resource": "document",
"operation": "insert",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "compliance",
"Collection": "audit_log",
"Documents": [
{
"eventType": "APPROVAL_DECISION",
"workflowId": "{{ $workflow.id }}",
"runId": "{{ $execution.id }}",
"actorId": "{{ $json.approverId }}",
"actorEmail": "{{ $json.approverEmail }}",
"decision": "{{ $json.decision }}",
"comments": "{{ $json.comments }}",
"targetType": "PurchaseOrder",
"targetId": "{{ $json.purchaseOrderId }}",
"timestamp": "{{ $now }}",
"tenantId": "{{ $json.tenantId }}"
}
],
"Ordered": true
}
