n8n Integration Guide

Automate document generation, traceability, printing, and more using the DataMagik n8n community node.

Table of Contents

1. Overview
2. Installation
3. Authentication Setup
4. Available Resources
5. Document Generation
6. Traceability & Serial Numbers
7. Lookup Tables
8. Printer Integration
9. Label Processing
10. Workflow Examples
11. Best Practices

1. Overview

The DataMagik n8n community node (n8n-nodes-datamagik) provides complete integration with the DataMagik API. Build automation workflows combining:

• Document Generation — Create PDFs with automatic completion waiting
• Traceability — Generate and track serial numbers
• Lookup Tables — Access key-value data stores
• Printing — Send jobs to industrial printers
• Labels — Process ZPL templates and generate previews

2. Installation

Option 1: Install via n8n UI (Recommended)

1. Go to Settings → Community Nodes
2. Enter n8n-nodes-datamagik
3. Click Install
4. Restart n8n

Option 2: Manual Installation

npm install n8n-nodes-datamagik

Option 3: Docker

environment:
  - N8N_CUSTOM_EXTENSIONS=n8n-nodes-datamagik

3. Authentication Setup

1. In n8n, go to Credentials
2. Click Add Credential
3. Search for DataMagik API
4. Enter your API Token (JWT Bearer token from Settings → API Keys in DataMagik)
5. Click Save

Authentication Methods:

4. Available Resources

5. Document Generation

List Templates

Operation: List Templates — Retrieves all available document templates.

Generate Document

Operation: Generate Document — Creates a document from a template with data substitution.

Example Template Data:

{
  "customer_name": "Acme Corporation",
  "invoice_number": "INV-2025-001",
  "amount": 1500.00,
  "items": [
    { "description": "Widget A", "quantity": 10, "price": 100.00 }
  ]
}

Automatic Completion: When using URL return type, the node automatically polls every 5 seconds for up to 2 minutes until the document is ready.

Important: Always provide template IDs as strings to avoid JavaScript number precision issues. Use {{ String($json.template_id) }} in expressions.

6. Traceability & Serial Numbers

List Series

Operation: List Series — Gets all configured serial number series.

Generate Serial

Operation: Generate Serial

Batch Generate Serials

Operation: Batch Generate Serials

Search Records

Operation: Search Records — Query traceability history by series, work order, date range, or status.

7. Lookup Tables

Lookup Value

Operation: Lookup

Bulk Create Data

Operation: Bulk Create Data — Import multiple key-value pairs.

[
  { "key": "PART-001", "value": { "description": "Widget", "price": 25.00 } },
  { "key": "PART-002", "value": { "description": "Gadget", "price": 50.00 } }
]

8. Printer Integration

List Printers

Operation: List Printers — Gets all registered printers.

Send Print Job

Operation: Send Print Job

9. Label Processing

Process Template

Operation: Process Template — Processes a ZPL template with data substitution.

Preview ZPL

Operation: Preview ZPL — Generates a PNG preview image of ZPL label code.

10. Workflow Examples

Invoice Generation from Webhook

[Webhook] → [DataMagik: Generate Document] → [Send Email]

1. Webhook receives order data
2. DataMagik generates invoice PDF
3. Send Email attaches the PDF and sends

Serial Number Labels for Production

[Schedule] → [DataMagik: Batch Generate] → [DataMagik: Process Template] → [DataMagik: Print]

1. Schedule triggers at shift start
2. Batch Generate creates 50 serials for the work order
3. Process Template generates ZPL for each serial
4. Print sends labels to the production printer

Document with Lookup Data

[Trigger] → [DataMagik: Lookup] → [DataMagik: Generate Document]

1. Trigger receives customer ID
2. Lookup fetches customer details
3. Generate Document creates invoice with complete data

Complete Manufacturing Flow

[Webhook: Work Order]
  → [DataMagik: Batch Generate Serials]
  → [Loop: For Each Serial]
    → [DataMagik: Process Template]
    → [DataMagik: Send Print Job]
  → [DataMagik: Generate Document (Certificate)]

11. Best Practices

Template IDs

• Always use strings for template IDs
• Use String() wrapper when getting from expressions
• Test with actual IDs before production

Error Handling

• Enable Continue on Fail for graceful error handling
• Check the success field in all responses
• Implement retry logic for transient failures

Performance

• Use URL return type for production workflows
• Batch operations when possible
• Monitor queue priorities for time-sensitive documents

Security

• Store API tokens using n8n credentials (never hardcode)
• Use HTTPS endpoints only
• Rotate tokens periodically

Troubleshooting

Required Permissions

Your API key user needs one of these permissions:

• DataMagik - User
• DataMagik - Builder
• DataMagik - Viewer

HTTP Request Alternative

If you prefer using the built-in HTTP Request node:

URL: https://data-magik.com/api/document-designer/generate
Method: POST
Headers: { "Authorization": "Bearer your_jwt_token", "Content-Type": "application/json" }
Body: {
  "template_id": "1097823044285431810",
  "format": "pdf",
  "return_type": "url",
  "data": { "customer_name": "{{ $json.customer_name }}" }
}

Note: When using HTTP Request, you must manually implement polling for document completion.