FlowRag — knowledge/insert

When to Use

New content publication: Trigger this operation whenever a new FAQ article, policy document, or product description is published. The document becomes immediately available for semantic retrieval.
Bulk knowledge base seeding: Use a Loop node to iterate over a document array and call knowledge/insert on each item to initialise a new collection from an existing content library.
Event-driven ingestion: Connect to a WebhookTrigger that fires when documents are added to a CMS, SharePoint library, or S3 bucket. Insert automatically on new uploads.
Incremental data loading: Insert new records as they are created in a database — e.g. insert a new product description each time a product is added to the catalogue.

Save the knowledgeId: The operation returns a knowledgeId GUID that uniquely identifies this document in the vector store. Store this value in your source system (CMS, database, etc.) so you can reference it for future knowledge/update and knowledge/delete operations without scanning the collection.

Configuration

Connection

Field	Required	Description
`providerName`	Required	Vector store provider. One of: `pinecone`, `weaviate`, `chroma`, `qdrant`, `pgvector`.
`collectionName`	Required	Target collection or index name in the vector store. Must already exist unless the provider auto-creates collections.
`credentialId`	Optional	Credential ID for the vector store API key or connection string, stored in the BizFirst Credentials Manager.
`embeddingProvider`	Optional	LLM provider for embedding generation, e.g. `openai`.
`embeddingCredentialId`	Optional	Credential ID for the embedding model API key.
`embeddingModel`	Optional	Embedding model, e.g. `text-embedding-3-small`. Must match the model used for all other items in this collection.

Operation

Field	Required	Description
`content`	Required	The text to embed and store. Supports `{{ expressions }}`. For best retrieval quality keep each insert focused on a single topic (200–500 tokens).
`fileName`	Optional	Original filename of the source document, e.g. `hr-pto-policy-2025.pdf`. Used for metadata and targeted operations later.
`source`	Optional	URL or file path of the source document, e.g. `https://intranet.acme.com/policies/pto`. Stored as metadata — AI nodes can cite this in responses.

Sample Configuration JSON

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "insert",
  "providerName": "qdrant",
  "collectionName": "hr-policies",
  "credentialId": "88",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "content": "{{ $input.policyText }}",
  "fileName": "{{ $input.fileName }}",
  "source": "{{ $input.sourceUrl }}"
}

Validation Errors

Error	Cause
`collectionName is required`	`collectionName` is empty or missing.
`providerName is required`	`providerName` is empty or missing.
`content is required`	`content` is empty after expression evaluation.

Output

Success Port

Field	Type	Description
`knowledgeId`	string (GUID)	Unique identifier assigned to this document in the vector store. Persist this in your source system for future update and delete operations.
`collection`	string	The collection name where the document was stored.
`chunkCount`	number	Number of embedding chunks created from the content. Long content may be split into multiple chunks for better retrieval granularity.
`status`	string	`"success"`
`errorMessage`	string	Empty on success.

Error Port

Fires when the insert fails. Common causes: vector store unreachable, invalid credentials, embedding API error, or collection does not exist.

Field	Type	Description
`knowledgeId`	string (GUID)	Empty GUID (`00000000-0000-0000-0000-000000000000`) when the insert failed.
`collection`	string	The collection name that was targeted.
`chunkCount`	number	`0` on error.
`status`	string	`"error"`
`errorMessage`	string	Human-readable error description from the vector store or embedding provider.

Sample Output JSON

Success

{
  "knowledgeId": "a3f2c1d4-8e5b-4a90-b231-7c6e9f12d847",
  "collection": "hr-policies",
  "chunkCount": 3,
  "status": "success",
  "errorMessage": ""
}

Error

{
  "knowledgeId": "00000000-0000-0000-0000-000000000000",
  "collection": "hr-policies",
  "chunkCount": 0,
  "status": "error",
  "errorMessage": "Collection 'hr-policies' not found in Qdrant. Create the collection before inserting documents."
}

Expression Reference

Expression	Returns
`{{ $output.insertNode.knowledgeId }}`	GUID of the newly inserted document.
`{{ $output.insertNode.collection }}`	Collection name where the document was stored.
`{{ $output.insertNode.chunkCount }}`	Number of embedding chunks created.
`{{ $output.insertNode.status }}`	`"success"` or `"error"`.
`{{ $output.insertNode.errorMessage }}`	Error description on failure, empty on success.

Node Policies & GuardRails

Policy	Detail
Credential isolation	Vector store API keys and embedding model API keys are stored in the BizFirst Credentials Manager and resolved at runtime. Never embed raw keys in node configuration.
Embedding model consistency	All documents in a collection must use the same embedding model. The node does not enforce this at insert time — mismatched models corrupt similarity scores silently. Establish and document a per-collection model standard.
Content size guidance	Keep each `content` payload to 200–500 tokens for optimal retrieval precision. Very large inserts produce coarse chunks that degrade semantic similarity matching.
Collection pre-existence	Most vector store providers require the collection or index to be created before inserting. If the collection does not exist, the operation fails to the error port with a descriptive message.
knowledgeId persistence	The returned `knowledgeId` is the only handle for future update and delete. If it is not persisted, the document can only be removed by deleting the entire collection.
Audit trail	Every insert operation is logged to the BizFirst execution audit trail with timestamp, collection, and knowledgeId for compliance and debugging.

Examples

Example 1 — Insert a New HR Policy Section

A scheduled workflow fetches published policy sections from the company intranet and inserts each section as a separate knowledge item.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "insert",
  "providerName": "pgvector",
  "collectionName": "company-policies",
  "credentialId": "55",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "content": "{{ $input.sectionText }}",
  "fileName": "{{ $input.policyDocumentName }}",
  "source": "https://intranet.acme.com/policies/{{ $input.policySlug }}"
}

The workflow saves the returned knowledgeId to a database record alongside the policy section ID for future reference.

Example 2 — Bulk Product Catalogue Ingestion via Loop

A one-time workflow seeds the product knowledge base from a JSON array of product records. A Loop node iterates over the array and calls FlowRag insert for each product.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "insert",
  "providerName": "qdrant",
  "collectionName": "product-catalogue",
  "credentialId": "88",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "content": "Product: {{ $item.name }}. Category: {{ $item.category }}. Description: {{ $item.description }}. Features: {{ $item.features | join(', ') }}.",
  "fileName": "product-catalogue-seed.json",
  "source": "https://api.acme.com/products/{{ $item.id }}"
}

The content string combines multiple product fields into a single descriptive passage, improving semantic retrieval when customers describe their needs in natural language.

Example 3 — Event-Driven Support Article Insert

A WebhookTrigger fires when a new article is published in Zendesk. FlowRag inserts the article body into the support knowledge base.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "insert",
  "providerName": "pinecone",
  "collectionName": "support-articles",
  "credentialId": "101",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "content": "{{ $trigger.article.title }}\n\n{{ $trigger.article.body }}",
  "fileName": "zendesk-article-{{ $trigger.article.id }}.txt",
  "source": "{{ $trigger.article.html_url }}"
}

A downstream DataMapping node saves the knowledgeId back to Zendesk as a custom field on the article so future update and delete operations can reference it directly.