Skip to main content

​
What is FlowX Database?

FlowX Database (FlowX DB) is a persistence layer that allows you to store structured data independently of process instances. This enables you to:
  • Share data between different process instances
  • Store and retrieve data across multiple processes
  • Create a persistent data store within the FlowX ecosystem
  • Access structured data without directly interacting with external systems
FlowX Database is powered by the nosql-db-runner microservice, which provides MongoDB functionality within the FlowX ecosystem. This service supports both native MongoDB and Azure Cosmos DB (MongoDB API), enabling you to choose the database backend that best fits your infrastructure needs while maintaining FlowX’s workflow integration capabilities.For more information about the nosql-db-runner service and CosmosDB considerations, see the NoSQL DB Runner documentation.

​
Key concepts

  • Data Sources
  • Collections
  • Operations
In the FlowX platform, Data Sources represent connections to different data repositories. With the introduction of FlowX Database, there are now two types of data sources available in the Integration Designer:
Data Source TypeDescription
RESTful SystemTraditional integration with external REST APIs
FlowX DatabaseConnection to the internal FlowX Database for data persistence
Each FlowX Database data source represents a collection in the underlying MongoDB database.

​
Prerequisites

Before working with FlowX Database, you should have a solid understanding of:

MongoDB Fundamentals

Basic knowledge of MongoDB operations, document structure, and query syntax

JSON Structure

Understanding of JSON payloads and data formatting

CRUD Operations

Familiarity with Create, Read, Update, and Delete operations in database systems

Query Modifiers

Knowledge of query parameters like filters, sorting, projection, and pagination
If you’re new to MongoDB, we recommend reviewing the MongoDB Manual before working with FlowX Database operations.

​
Benefits of FlowX Database

Data Sharing

Share data between different process instances, enabling more complex workflows and business scenarios

Independence

Store data structured according to your needs, independent of external systems

Extended Use Cases

Enable new business cases that require persistent data across multiple processes

Simplified Integration

Reduce the need for creating custom connectors to external systems for basic data persistence

Native Integration

Integrate with workflows through the existing workflow designer

Complete CRUD Operations

Perform all standard Create, Read, Update, and Delete operations on your data

Bulk Operations

Handle multiple documents efficiently with insertMany, updateMany, and deleteMany operations

Flexible Querying

Use MongoDB’s powerful query syntax to filter, sort, and project your data

​
How to use FlowX Database

​
Creating a collection

1

Access Data Sources

Navigate to the ‘Integrations’ section in the left sidebar of FlowX Designer, then click on ‘Data Sources’.

Accessing Data Sources in the navigation menu

2

Add a new Data Source

Click the ”+” button to add a new Data Source. In the “Add Data Source” dialog, select “FlowX Database” from the dropdown list.

Adding a new FlowX Database data source

3

Configure the collection

Provide a name and description for your collection. The name will be used to identify this database collection in your workflows.
Data Model Required: You must have a data model defined before creating a FlowX Database collection. The data model becomes the schema for your database collection and defines the structure of documents that will be stored.

Configuring the collection

  • Schema Definition: Define the schema for your collection (the selected schema enhances auto-completion but does not enforce validation during insert or update)
  • Partitioning Key: The attribute used to partition data in your collection. By default, this is set to the id attribute, but you can specify a different field based on your data model.
4

Create the collection

Click “Create” to save the collection in FlowX Database. Your new collection will appear in the Data Sources list with the type “FlowX Database”.
Each FlowX Database data source represents a collection in the underlying MongoDB database. When you create a new data source with the FlowX Database type, you’re essentially creating a new collection where your documents will be stored.

​
Viewing collection data

1

Navigate to collection

Go to the collection you want to view in the ‘Data Sources’ section.
2

Access Documents tab

Click the ‘Documents’ section within the collection.
3

Browse documents

You’ll see a listing of currently saved documents in the collection.

Viewing documents in a FlowX Database collection

4

Search and filter

Use the search functionality to find specific documents in the collection. You can add queries to filter documents, sort them, and use projections to choose what content from each entry you want to see.

Searching and filtering documents in a FlowX Database collection

FlowX Database currently relies on MongoDB’s native sorting behavior for query results. All sorting is performed using MongoDB’s default binary comparison rules.

​
Managing collection settings

Each FlowX Database collection has a Settings tab where you can configure performance optimizations:
1

Access Settings tab

Navigate to your collection and click on the ‘Settings’ tab.
2

Define indexes

Create indexes for your collection to improve query performance. Indexes are particularly important for large collections as they significantly reduce query execution time.
Create indexes on fields that you frequently use in filter conditions, sort operations, or queries to optimize performance.

Defining indexes for a FlowX Database collection

For large collections with thousands of documents, proper indexing is crucial for maintaining good query performance. Consider indexing frequently queried fields before your collection grows large.

​
Creating database operations

  • Create operation
  • Update operation
  • Delete operation
1

Access operations list

Navigate to your FlowX Database collection in the Data Sources section.
2

Create new operation

Click the ”+” button to create a new operation.

Creating a new operation for a FlowX Database collection

3

Select operation type

Choose the operation type from the dropdown (find, findOne, insertOne, insertMany, etc.).

Selecting the operation type

4

Name the operation

Give your operation a meaningful name and description that indicates its purpose.
5

Define the operation parameters

Configure the parameters for your operation based on its type. For example, for a find operation:

Configuring operation parameters

  • Filter: Define the criteria to match documents
  • Projection: Select which fields to include in the results
  • Sort: Specify the sorting order
  • Skip: For find operations, specify the number of documents to skip
  • Limit: Set the maximum number of documents to return
Parameter Syntax: When defining operation parameters, remember:
  • Parameters defined in the operation are referenced using ${parameterName} syntax
  • Database field names must be in quotes (e.g., "firstName", "customerId")
  • Parameters don’t need to match your data model exactly - they’re placeholders that get replaced with actual values
  • Field names in quotes must match exactly what’s stored in the database (same as your data model)
6

Test the operation

Use the test functionality to verify your operation works correctly.

Testing an operation

Testing Delete Operations: Be extremely careful when testing delete operations (deleteOne and deleteMany) as they will actually remove documents from your collection. Always use test data or ensure you have backups before testing deletion operations in collections with important data.
7

Save the operation

Click “Save” to add the operation to your collection. It will now be available for use in workflows.

​
Working with FlowX Database in workflows

Database node in a workflow

FlowX Database integrates directly with the workflow designer through the “Data Source” node type:
1

Add Data Source node

In your workflow, add a new node and select the ‘DATA_SOURCE’ type.
2

Configure data source

In the node properties panel:

Data Source node configuration

  1. Choose “FlowX Database” as the system type from the dropdown
  2. Select your collection from the available options
  3. Choose the operation you want to perform (find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany)
3

Configure operation parameters

Set the parameters for your selected operation. The available parameters will depend on the operation type:
  • filter - For find operations, define the criteria to match documents
  • sort - For find operations, specify the sorting order for results
  • document - For insert operations, define the document to insert
  • update - For update operations, define the document to update
  • delete - For delete operations, define the criteria to match documents
  • skip - For find operations, specify the number of documents to skip
  • limit - For find operations, specify the maximum number of documents to return
  • projection - For find operations, specify the fields to include or exclude in the results

Configuring operation parameters

You can use static JSON or reference process variables using the expression syntax.
4

Set response key

Specify where the operation result should be stored in the process instance. This makes the data available to subsequent nodes in your workflow.
{
  "age": { "$gt": 30 },
  "status": "active"
}
This filter will return all documents where the age is greater than 30 and the status is “active”.
For more information about MongoDB comparison operators like $gt, see Comparison Query Operators.
{
  "customerId": "${processInstance.customerData.id}"
}
This filter uses a value from the process instance to find documents matching a specific customer ID.
Learn more about MongoDB query syntax in the Query Documents Tutorial.

​
MongoDB operations supported

FlowX Database leverages MongoDB’s powerful query capabilities through the nosql-db-runner service, providing pure MongoDB functionality. For detailed information about MongoDB query operators, filters, and syntax, refer to the MongoDB Query and Projection Operators documentation. The following MongoDB operations are supported in FlowX Database. Each tab includes practical examples that you can use as a starting point for your own operations.
  • find
  • findOne
  • insertOne
  • insertMany
  • updateOne
  • updateMany
  • deleteOne
  • deleteMany
Parameters:For complete documentation on find operations and query syntax, see MongoDB db.collection.find().
This example finds all active customers, sorts them by registration date (newest first), limits to 10 results, and returns only specific fields.Operation name: listActiveCustomers
  • filter
  • sort
  • projection
  • limit
{
  "status": "active"
}
This operation will return up to 10 active customers, with the most recently registered customers first.
This example finds products in a specific category within a price range.Operation name: findAffordableElectronics
  • filter
  • sort
  • projection
  • limit
{
  "category": "electronics",
  "price": { "$gte": 10, "$lte": 100 }
}
This operation will return up to 20 electronics products with prices between 10and10 and 100, sorted from lowest to highest price.
Always use caution with update and delete operations, especially those that affect multiple documents (updateMany, deleteMany). Always include specific filter criteria to avoid unintended changes to your data.

​
Real-world example: Customer management system

This example demonstrates how a customer management system could use FlowX Database to persist and share customer data across different processes.
1

Create Customer collection

Create a new FlowX Database data source named “Customers”.
2

Define operations

Create the following operations:
  • findCustomer
  • createCustomer
  • updateCustomerStatus
  • listActiveCustomers
Operation Type: findOne
Parameters:
{
  "filter": {
    "customerId": "${processInstance.customerId}"
  },
  "projection": {
    "firstName": 1,
    "lastName": 1,
    "email": 1,
    "phone": 1,
    "status": 1,
    "customerSince": 1,
    "_id": 0
  }
}
This operation retrieves a single customer by their customerId, returning only selected fields.
In this process:
  1. Support agent enters the customer ID
  2. A Data Source node retrieves the customer details from the Customers collection
  3. Customer information is displayed to the agent
  4. After resolving the issue, the support agent updates the customer status
  5. Another Data Source node updates the customer record in the database

This example shows how FlowX Database:
  • Enables data persistence across multiple processes
  • Provides a single source of truth for customer data
  • Simplifies data retrieval and updates
  • Eliminates the need for external systems to store basic customer information

​
Limitations and considerations

​
Best practices

Design before implementation: Plan your collections and operations carefully before implementation.
Keep document structure simple: Avoid deeply nested structures for better performance and easier querying.
Use meaningful names: Choose clear names for collections and operations.
Limit document size: Keep individual documents under 16MB for optimal performance.
Test operations thoroughly: Use the testing functionality to ensure operations work as expected.
Consider indexing: For large collections, consider indexing frequently queried fields.
Provide default values: Ensure all data types have default values (e.g., empty string for null, 0 for integers).

​
Troubleshooting

1

Problem

Find operation fails with an error related to the filter syntax.
2

Solution

Check your filter syntax to ensure it follows MongoDB query syntax. Common issues:
  • Missing quotes around string values
  • Incorrect operator syntax (e.g., using > instead of $gt)
  • Mismatched brackets or braces
1

Problem

Your query doesn’t return expected documents.
2

Solution

  • Verify your filter conditions are correct
  • Check if documents actually exist in the collection
  • Try a more general query to see if documents are returned
  • Check if field names in your filter match exactly with the document structure
1

Problem

Queries returning large amounts of data are slow.
2

Solution

  • Add pagination using skip and limit parameters
  • Add more specific filter conditions
  • Use projection to return only needed fields
  • Consider indexing frequently queried fields
1

Problem

Insert operation fails with an error.
2

Solution

  • Check that your document JSON is valid
  • Ensure document size is under 16MB
  • Verify all required fields are present
  • Check for any unique constraint violations

Data Search

Learn about the Data Search service for indexing and searching process data.

Integration Management

Understand how to manage integrations with external systems.

Workflow

See how workflows can interact with data sources.

Process Data Model

Learn about data models used within processes.

​
Summary

FlowX Database provides a powerful persistence layer that enables you to store and share data across different processes and projects. By leveraging MongoDB’s capabilities through the nosql-db-runner service, FlowX Database offers:
  1. Flexible data storage for any structured data
  2. Data sharing between process instances
  3. Integration with workflows
  4. Independence from external systems for basic data persistence

​
MongoDB learning resources

To get the most out of FlowX Database, familiarize yourself with MongoDB concepts and operations:

MongoDB Manual

Complete MongoDB documentation covering all operations and concepts

Query Tutorial

Learn how to construct effective MongoDB queries

Update Operations

Master document update operations and operators

Data Modeling

Best practices for structuring your data in MongoDB

​
FAQs

FlowX Database does not replace Data Search. Each serves different purposes in the platform.
  • FlowX Database
  • Acts as a persistent data store
  • Optimized for CRUD operations
  • Stores structured business data
  • Designed for sharing data across processes
  • Uses MongoDB as the underlying technology (via nosql-db-runner service)
FlowX Database is designed for operational data with temporary character, including:
  • Dashboard data: Aggregated information for reporting and visualization. For example, create operations that gather information from multiple processes and pull all the data to calculate sums, averages, or other metrics for executive dashboards
  • Cached data: Frequently accessed information that changes periodically, such as:
    • Daily exchange rates for financial calculations
    • Product catalogs that update weekly
    • Configuration data that multiple processes need to access
  • Internal operational comments: Information that needs to be shared between users but shouldn’t reach business systems, such as:
    • Internal comments in a client’s profile for bank tellers
    • Notes and annotations that support decision-making across different process instances
    • Communication logs between team members working on the same case
  • Shared process data: Information that needs to be accessed across multiple process instances - this solves the key pain point of data sharing between different process instances
  • Temporary operational data: Working data that supports business processes but isn’t part of your permanent records
Important: FlowX Database should not become your primary book of records or system of record. Use it for operational data that supports your processes, not for critical business data that requires long-term retention and governance.
Yes, you can share collections between projects using the library approach:
  1. Create collections in one project: Set up your FlowX Database collections in a primary project
  2. Include as libraries: Add these collections as libraries in other projects that need access
  3. Maintain consistency: This approach ensures all projects use the same data structures and operations
  4. Future-proof management: Having centralized collection definitions makes updates and maintenance easier across all projects
This pattern is particularly useful for shared reference data, common configurations, or cross-project operational data.
Collection Ownership: Each FlowX Database collection has an owner - either the project where it was created or the library that contains it. By default, only processes and workflows within the same project can access a collection. If you need to access the same collection from multiple projects, create it in a library and then include that library in all projects that need access.
FlowX Database intentionally does not provide automatic migration capabilities for several important reasons:
  • Data integrity: Many documents need to remain in their original format to maintain historical accuracy and compliance requirements
  • Process dependencies: Existing processes may depend on specific data structures, and automatic changes could break functionality
  • Business context: Data migration often requires business logic and context that automated systems cannot provide
  • Risk management: Manual migration allows for proper testing and validation before changes are applied
When you need to modify data structures, plan for manual migration processes with proper testing and validation procedures handled by your DevOps team.
No, this is strongly discouraged. Each collection should contain documents with the same structure and purpose.DON’T DO IT - Mixing different document types in one collection can lead to:
  • Query complexity: Filtering becomes more complex when documents have different schemas
  • Performance issues: Indexes become less effective with mixed document types
  • Maintenance problems: Updates and changes become harder to manage
  • Data consistency: Harder to ensure data quality and validation
Instead, create separate collections for each document type, even if they seem related. This follows MongoDB best practices and keeps your data organized and manageable.
FlowX Database solves the key pain point of accessing the same data from multiple process instances:
  • Cross-instance access: Multiple process instances can read from and write to the same collections simultaneously
  • Data persistence: Data remains available even after individual processes complete
  • Concurrent access: The underlying MongoDB technology (via nosql-db-runner) handles concurrent read/write operations safely
  • Shared state: Enables complex workflows where processes need to coordinate through shared data
This capability enables use cases like multi-step approval processes, shared customer data across different business processes, and coordinated workflows that span multiple process instances - addressing a major limitation of traditional process-scoped data storage.
FlowX Database is powered by the nosql-db-runner microservice, which provides:
  • Pure MongoDB functionality: Direct access to MongoDB operations within the FlowX ecosystem
  • Native integration: Connection between FlowX workflows and MongoDB operations
  • Scalable architecture: A dedicated service that can be scaled independently based on database operation needs
The nosql-db-runner acts as the bridge between FlowX’s workflow engine and MongoDB, enabling you to leverage MongoDB’s full power while maintaining FlowX’s process orchestration capabilities.
⌘I