n8n Integration Guide

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

📸 Screenshot Needed: n8n workflow canvas showing a DataMagik node connected in a workflow. Open n8n and create a workflow with the DataMagik node to capture this.

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 Manufacturing & Document Automation API. Build powerful 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

Key Features:

• Automatic Polling — Built-in intelligent polling for document generation (up to 2 minutes)
• Binary Downloads — Automatically downloads binary data when needed
• Error Handling — Comprehensive error handling with continue-on-fail support
• Type Safety — Proper handling of large template IDs as strings

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 for the node to be recognized

📸 Screenshot Needed: n8n Community Nodes settings page showing the DataMagik node installed.

Option 2: Manual Installation

npm install n8n-nodes-datamagik

Then restart your n8n instance.

Option 3: Docker Installation

Add to your n8n Dockerfile or docker-compose:

environment:
  - N8N_CUSTOM_EXTENSIONS=n8n-nodes-datamagik

3. Authentication Setup

Create Credentials

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

📸 Screenshot Needed: The DataMagik API credential configuration screen.

Getting Your API Token

1. Log in to DataMagik at https://data-magik.com
2. Navigate to Settings → API Keys
3. Create a new API key or copy an existing one
4. The token is a JWT format: eyJhbGciOiJIUzI1NiIs...

Credential Test

The node automatically tests credentials by calling /api/health. A successful test confirms your token is valid.

Authentication Methods

The API supports two methods:

Bearer Token (Recommended):

Authorization: Bearer your_jwt_token

X-API-Key Header:

X-API-Key: your_api_key

4. Available Resources

The DataMagik node provides five main resources:

ResourceDescriptionDocumentGenerate PDFs and HTML documents from templatesTraceabilityManage serial number series and generate serialsLookup TableAccess and manage key-value lookup tablesPrinterSend print jobs to registered printersLabelProcess ZPL templates and generate previews

📸 Screenshot Needed: The DataMagik node configuration panel showing the Resource dropdown.

5. Document Generation

List Templates

Retrieve all available document templates.

Operation: List Templates

Output:

{
  "success": true,
  "templates": [
    {
      "template_id": "1097823044285431810",
      "name": "Invoice Template",
      "description": "Standard invoice",
      "format": "pdf",
      "version": "v7",
      "branch": "main"
    }
  ]
}

Generate Document

Create a document from a template with data substitution.

Operation: Generate Document

Parameters:

ParameterDescriptionRequiredTemplate IDTemplate identifier (as string)YesFormatOutput format: pdf or htmlYesReturn Typeurl (download link) or binary (file data)YesTemplate DataJSON object with data for the templateYesPriorityQueue priority: urgent, high, normal, lowNoCustom FilenameOverride the default filenameNo

📸 Screenshot Needed: The Generate Document operation configuration with parameters filled in.

Example Template Data:

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

Automatic Completion:

When using URL return type, the node automatically:

1. Submits the generation request
2. Polls every 5 seconds for completion
3. Returns the result when ready (up to 2 minutes)
4. Throws an error if generation fails or times out

Output (URL Return Type):

{
  "success": true,
  "document_id": "1109244902871826434",
  "download_url": "https://data-magik.com/api/document/download/abc123",
  "filename": "Invoice_2025-001.pdf",
  "format": "pdf",
  "metadata": {
    "processingTimeMs": 2841,
    "fileSizeBytes": 60022,
    "templateName": "Invoice Template"
  }
}

Output (Binary Return Type):

Returns the document as binary data, ready for further processing or sending as an attachment.

Important: Template ID as String

Always provide template IDs as strings to avoid JavaScript number precision issues:

✅ Correct: "1097823044285431810" ❌ Incorrect: 1097823044285431810

When using expressions from previous nodes:

{{ String($json.template_id) }}

6. Traceability & Serial Numbers

List Series

Get all configured serial number series.

Operation: List Series

Output:

{
  "success": true,
  "series": [
    {
      "series_id": 1,
      "name": "Product Serials",
      "format_string": "SN-{YYYY}{JJJ}-{####}",
      "base_type": "numeric",
      "current_value": 42
    }
  ]
}

Generate Serial

Generate a single serial number from a series.

Operation: Generate Serial

Parameters:

ParameterDescriptionRequiredSeries NameName of the seriesYesWork OrderAssociated work orderNoPart NumberAssociated part numberNoContext DataAdditional metadata (JSON)No

Output:

{
  "success": true,
  "serial_number": "SN-2025166-0043",
  "series_id": 1,
  "record_id": 12345
}

Batch Generate Serials

Generate multiple serial numbers at once.

Operation: Batch Generate Serials

Parameters:

ParameterDescriptionRequiredSeries NameName of the seriesYesQuantityNumber of serials to generateYesWork OrderAssociated work orderNoPart NumberAssociated part numberNo

Output:

{
  "success": true,
  "serials": [
    "SN-2025166-0044",
    "SN-2025166-0045",
    "SN-2025166-0046"
  ],
  "count": 3
}

Search Records

Query traceability history with flexible filters.

Operation: Search Records

Parameters:

ParameterDescriptionSeries NameFilter by seriesWork OrderFilter by work orderDate RangeFilter by generation dateStatusFilter by status

7. Lookup Tables

Lookup Value

Retrieve a value from a lookup table by key.

Operation: Lookup

Parameters:

ParameterDescriptionRequiredTable NameName of the lookup tableYesKeyKey to look upYes

Output:

{
  "success": true,
  "key": "PART-001",
  "value": {
    "description": "Standard Widget",
    "price": 25.00,
    "category": "Components"
  }
}

Bulk Create Data

Import multiple key-value pairs into a lookup table.

Operation: Bulk Create Data

Parameters:

ParameterDescriptionRequiredTable NameName of the lookup tableYesDataArray of key-value objectsYes

Example Data:

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

8. Printer Integration

List Printers

Get all registered printers for your account.

Operation: List Printers

Output:

{
  "success": true,
  "printers": [
    {
      "printer_id": 1,
      "name": "Warehouse-Zebra-01",
      "ip_address": "192.168.1.100",
      "port": 9100,
      "type": "zebra",
      "protocol": "raw_socket",
      "is_zpl_compatible": true
    }
  ]
}

Send Print Job

Send data to a printer.

Operation: Send Print Job

Parameters:

ParameterDescriptionRequiredPrinter NameName of the registered printerYesFormatzpl, pdf, or rawYesDataContent to printYesCopiesNumber of copiesNo

Example ZPL Data:

^XA
^FO50,50^A0N,40,40^FDHello World^FS
^FO50,100^BY3^BCN,100,Y,N,N^FD123456789^FS
^XZ

9. Label Processing

Process Template

Process a ZPL template with dynamic data substitution.

Operation: Process Template

Parameters:

ParameterDescriptionRequiredTemplate NameName of the ZPL templateYesDataJSON data for substitutionYes

Output:

{
  "success": true,
  "zpl": "^XA^FO50,50^A0N,40,40^FDPN-12345^FS...^XZ"
}

Preview ZPL

Generate a PNG preview image of ZPL label code.

Operation: Preview ZPL

Parameters:

ParameterDescriptionRequiredZPL CodeRaw ZPL codeYesWidthLabel width in dotsNoHeightLabel height in dotsNoDPIPrinter DPI (203 or 300)No

Output: Binary PNG image data

10. Workflow Examples

Example 1: Invoice Generation from Webhook

Trigger document generation when a webhook is received:

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

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

📸 Screenshot Needed: Workflow showing webhook → DataMagik → email nodes connected.

Example 2: Serial Number Labels for Production

Generate serials and print labels for a work order:

[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

Example 3: Document with Lookup Data

Enrich documents with lookup table data:

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

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

Example 4: 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 (e.g., batch serial generation)
• Monitor queue priorities for time-sensitive documents

Security

• Store API tokens using n8n credentials (never hardcode)
• Use HTTPS endpoints only
• Rotate tokens periodically
• Limit API key permissions to what's needed

Quotas

Monitor quota information in responses:

{
  "metadata": {
    "max_documents_per_month": 1000,
    "remaining_documents": 850,
    "max_storage_gb": 10.0,
    "remaining_storage_gb": 8.5
  }
}

Rate Limiting

• Implement reasonable delays between requests
• Use batch operations to reduce API calls
• Handle 429 (Too Many Requests) responses gracefully

Testing

• Test workflows with sample data first
• Verify document output before production
• Test printer connectivity before relying on print jobs

HTTP Request Node Alternative

If you prefer using the built-in HTTP Request node instead of the DataMagik 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 }}",
    "amount": "{{ $json.total_amount }}"
  }
}

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

Screenshots Summary

Please capture the following screenshots to complete this documentation:

1. n8n workflow canvas - DataMagik node in a workflow
2. Community Nodes settings - DataMagik node installed
3. Credential configuration - DataMagik API credential setup
4. Resource dropdown - Available resources in the node
5. Generate Document config - Operation parameters filled in
6. Example workflow - Complete workflow with multiple nodes

Troubleshooting

Common Issues

IssueSolutionAuthentication failedVerify API token is correct and not expiredTemplate not foundCheck template ID is a string, verify permissionsAccess deniedEnsure API key has required permissionsTimeoutIncrease polling timeout or check API healthInvalid JSONValidate template data is proper JSON format

Required Permissions

Your API key user needs one of these permissions:

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