n8n Integration Platform

1. Purpose and scope

This concept describes how n8n is operated as the central integration platform (P01): instances, access, security, logging, error handling, backup and how workflows are built. It puts the handout's principle P08 into practice (the same operating standards for all workflows, whoever builds them).

Out of scope are the business decisions E01–E10 (e.g. SAP document type, bundling, invoice structure). The platform is designed to support any of these options.

2. Instances and environments

The integration platform gets its own n8n instances: one for test and one for production. The test instance is connected only to test systems (Planon test, SAP development tenant, etc.). The IDP remains on its own instance.

Why separate instances: The Community Edition offers no separation of permissions or projects within one instance. A shared instance would mix the credentials, workload and update cycles of two service providers. Separate instances give clear responsibility and limit the impact of failures. The instances can run as individual containers on the same server.

IDP ↔ integration platform: via defined, authenticated HTTP interfaces (webhooks). Production talks to production; an IDP test environment, if there is one, talks to our test instance.

3. Hosting and access

• HTTPS is mandatory for all instances, with a reverse proxy in front: preferably Intesia's existing infrastructure; if there is none, Caddy with automatic certificates (Let's Encrypt).
• Each instance gets its own subdomain (e.g. n8n.… / n8n-test.…).
• n8n runs on PostgreSQL instead of the default SQLite database.

4. Authentication

Outbound (n8n calls Planon, SAP, Docuware): we use each system's standard method for machine-to-machine access, preferably OAuth2 client credentials, otherwise API key or certificate. Each system and environment gets its own technical user with minimal permissions.

Inbound (IDP, partners and webhooks call n8n): OAuth2 with JWT via Intesia's OAuth provider. A central “verify JWT” workflow checks every inbound call against the provider's current keys.

Credentials are stored encrypted in the n8n database. The encryption key (N8N_ENCRYPTION_KEY) is kept securely for each instance, separate from the backups.

5. Logging and error handling

We distinguish three levels:

1. System logs from n8n (start-up, errors, load), written to log files.
2. Execution data (every workflow run with all its data), kept in n8n. It is used for troubleshooting, not as a record. The retention period is set deliberately, as the data contains complete business records.
3. Business log: one entry per transaction, e.g. “Cluster CL-2026-10-4711 handed over to SAP, SAP document 1000004307, OK”. Each entry carries a correlation ID (e.g. the Planon work order number) so that a transaction can be traced across all systems. The log is kept in a separate database on the PostgreSQL server and written via a central “write log” workflow.

Error handling: A central error workflow runs on every failure, writes it to the business log and sends an alert. An error tracking tool (grouping of identical errors, dashboard, alert rules) is in place before go-live: either Sentry as a cloud service or the lightweight, Sentry-compatible GlitchTip on our own server.

6. Backup

To be agreed with Intesia (see O4). Proposal: regular backups to a dedicated S3 storage, separate from the server. The encryption key is kept separately from the backups.

7. How workflows are built

• Shared building blocks are built once and used by all workflows: “write log”, “verify JWT”, the error workflow, and one connection block per target system (e.g. Planon, SAP).
• Consistent naming, e.g. CORE-… for core logic, ADP-<partner>-In/Out for partner adapters.
• Versioning: workflows are stored as JSON in a Git repository and promoted from test to production.

8. Partner adapters

Customer and service provider systems (e.g. Service Channel) are connected following a fixed pattern (handout E02, option O1):

• One adapter per partner only translates between the partner's format and the internal format.
• One shared core workflow is the only one that talks to Planon.
• Mapping tables (e.g. partner store → Planon property, priority → SLA) are kept in PostgreSQL and can be maintained without changing workflows.
• Proposal for the internal ticket format: we define it based on the first real partner and also look at one or two other widely used ticket systems, so that the format is not tailored to a single partner. This still needs a closer look before it is fixed.

A new partner therefore only requires a new adapter.

9. Open points