Crosstech Impl N8n Aec Pipeline

crosstech-impl-n8n-aec-pipeline

Quick Reference

Core n8n Nodes for AEC Automation

Critical Warnings

NEVER run heavy IFC geometry processing inside n8n Code nodes — n8n runs JavaScript with a 10-second default timeout. ALWAYS delegate to external Python services via Execute Command or HTTP Request.

NEVER store IFC files in n8n's JSON data flow — binary files MUST be handled via file system paths or binary properties. n8n nodes pass JSON arrays between them; embedding multi-MB binary data causes memory exhaustion.

NEVER hardcode credentials in workflow JSON — ALWAYS use n8n's encrypted credential store. Workflow JSON is exportable and shareable; embedded secrets leak.

ALWAYS set explicit timeouts on Execute Command nodes running IfcOpenShell scripts — large IFC files (100MB+) can take minutes to process. The default timeout causes silent failures.

Technology Boundary

Side A: n8n Workflow Engine (v1.x)

Side B: AEC Tool APIs (Speckle, ERPNext, IfcOpenShell)

The Bridge: HTTP / Webhook / CLI Integration

n8n connects to AEC services through three integration patterns:

1. HTTP Request nodes → REST/GraphQL APIs (Speckle, ERPNext, IfcPipeline)
2. Webhook nodes → receive push events from Speckle commits, file uploads
3. Execute Command nodes → invoke IfcOpenShell Python scripts on the host

Data transformation happens in Code nodes (JavaScript) between these boundary crossings. The Code node transforms AEC-specific JSON structures into the format expected by the next service.

Data loss at boundary: IFC geometry is NEVER transmitted through n8n's JSON pipeline. Only metadata, quantities, and validation results cross the n8n boundary. Geometry stays in IFC files on disk or in dedicated services.

Critical Rules

1. ALWAYS delegate IFC processing to external services — n8n is an orchestrator, not a compute engine
2. ALWAYS use $binary properties for file transfers — NEVER base64-encode IFC files into JSON fields
3. ALWAYS configure Error Trigger nodes (n8n-nodes-base.errorTrigger) for every production pipeline
4. ALWAYS use Execute Sub-workflow for reusable pipeline stages (validation, notification)
5. NEVER process IFC geometry in Code nodes — Code nodes run JavaScript with limited memory and timeout
6. NEVER expose webhook URLs without authentication in production — use header auth or webhook path secrets
7. ALWAYS set continueOnFail: true on non-critical nodes to prevent full pipeline abort
8. ALWAYS store AEC service credentials in n8n's credential store with the correct type

Decision Tree

Need to automate an AEC workflow?
├── Trigger type?
│   ├── File upload event → Webhook node (POST, binary)
│   ├── Speckle model commit → Webhook node (Speckle webhook callback)
│   ├── Scheduled check → Schedule Trigger node (cron expression)
│   └── Manual/API trigger → Manual Trigger or Webhook node
├── Need IFC processing?
│   ├── Light metadata extraction → Execute Command (IfcOpenShell script)
│   ├── Heavy geometry operations → HTTP Request to IfcPipeline service
│   ├── Validation/clash detection → HTTP Request to IfcPipeline `/ifctester` or `/ifcclash`
│   └── Format conversion → HTTP Request to IfcPipeline `/ifcconvert`
├── Need to update external system?
│   ├── ERPNext BOM/Item → HTTP Request (POST /api/resource/:doctype)
│   ├── Speckle stream → HTTP Request (GraphQL mutation)
│   ├── Notification → Send Email or HTTP Request (Slack/Teams webhook)
│   └── File delivery → FTP/SFTP node
└── Error handling?
    ├── Validation failure → If node routes to notification branch
    ├── Service down → Error Trigger → retry or alert
    └── Partial failure → continueOnFail: true on non-critical nodes

Essential Patterns

Pattern 1: IFC Upload → Validation → Extraction → Report

Flow: Webhook → Execute Command (validate) → If → Execute Command (extract) → HTTP Request (ERPNext) → Send Email

[Webhook: IFC Upload] → [Execute Command: validate_ifc.py]
    → [If: valid?]
        ├── YES → [Execute Command: extract_quantities.py]
        │         → [Code: transform to ERPNext format]
        │         → [HTTP Request: POST /api/resource/BOM]
        │         → [Send Email: success report]
        └── NO  → [Send Email: validation failure report]

Webhook node configuration:

• Method: POST
• Path: ifc-upload
• Binary Property: ifc_file
• Options: rawBody: true

Execute Command configuration:

• Command: python3 /scripts/validate_ifc.py --input /tmp/{{ $binary.ifc_file.fileName }}
• ALWAYS use absolute paths to scripts
• ALWAYS pass file paths, not file content

Pattern 2: Speckle Webhook → Change Detection → Notification

Flow: Webhook → HTTP Request (Speckle GraphQL) → Code (diff) → If → HTTP Request (notify)

[Webhook: Speckle commit] → [HTTP Request: fetch commit details]
    → [Code: compare with previous commit]
    → [If: significant changes?]
        ├── YES → [HTTP Request: Slack notification]
        └── NO  → [No operation]

Speckle GraphQL query for commit details:

query {
  stream(id: "{{ $json.payload.streamId }}") {
    commit(id: "{{ $json.payload.commitId }}") {
      message
      authorName
      createdAt
      referencedObject
    }
  }
}

Pattern 3: Scheduled BIM Quality Check → Report → Email

Flow: Schedule Trigger → Execute Command (quality check) → Code (format) → Send Email

[Schedule Trigger: 02:00 daily] → [Execute Command: bim_quality_check.py]
    → [Code: format HTML report]
    → [Send Email: distribute to project team]

Schedule Trigger configuration:

• Rule: 0 2 * * * (daily at 02:00)
• Timezone: project-local timezone

Common Operations

Credential Configuration for AEC Services

HTTP Request to ERPNext API

{
  "method": "POST",
  "url": "https://erp.example.com/api/resource/BOM",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "={{ JSON.stringify({ data: { item: $json.item_code, items: $json.bom_items, quantity: 1 } }) }}"
}

Execute Command for IfcOpenShell

{
  "command": "python3 /scripts/extract_quantities.py --input \"{{ $json.file_path }}\" --format json",
  "timeout": 120000
}

ALWAYS set timeout to at least 120000ms (2 minutes) for IFC processing scripts. Large models require 5-10 minutes — set timeout accordingly.

IfcPipeline Integration via HTTP Request

{
  "method": "POST",
  "url": "http://ifcpipeline:8000/ifctester",
  "authentication": "genericCredentialType",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "={{ JSON.stringify({ ifc_file: $json.file_path, ids_file: '/specs/project.ids' }) }}"
}

IfcPipeline endpoints:

Error Handling Pattern

ALWAYS add an Error Trigger workflow that catches failures from production pipelines:

[Error Trigger] → [Code: format error details]
    → [If: severity]
        ├── CRITICAL → [Send Email: ops team] + [HTTP Request: Slack alert]
        └── WARNING  → [Send Email: project lead]

Set continueOnFail: true on nodes where partial failure is acceptable (e.g., notification nodes).

Sub-workflow Pattern for Reusable Stages

Extract common operations into sub-workflows called via Execute Sub-workflow node:

• IFC Validation Sub-workflow: Webhook input → validate → return pass/fail JSON
• ERPNext BOM Creation Sub-workflow: JSON input → create Items → create BOM → return BOM name
• Notification Sub-workflow: message + recipients → email + Slack

n8n-nodes-ifcpipeline Community Node

The n8n-nodes-ifcpipeline package (install via n8n Community Nodes) provides dedicated nodes for IfcPipeline operations without manual HTTP configuration:

# Install in n8n (Settings → Community Nodes)
n8n-nodes-ifcpipeline

This replaces manual HTTP Request configuration for all /ifc* endpoints with visual node configuration.

Reference Links

• references/methods.md — n8n node reference, API endpoints, credential setup
• references/examples.md — Complete workflow JSON snippets for AEC pipelines
• references/anti-patterns.md — Common n8n AEC pipeline mistakes

Official Sources

• https://docs.n8n.io/integrations/builtin/core-nodes/ — n8n core node reference
• https://docs.n8n.io/hosting/installation/server-setups/docker-compose/ — n8n Docker deployment
• https://docs.n8n.io/code/builtin/overview/ — n8n Code node reference
• https://speckle.guide/dev/server-webhooks.html — Speckle webhook documentation
• https://frappeframework.com/docs/user/en/api/rest — ERPNext/Frappe REST API
• https://github.com/jonatanjacobsson/ifcpipeline — IfcPipeline project
• https://github.com/jonatanjacobsson/n8n-nodes-ifcpipeline — n8n-nodes-ifcpipeline community node