N8N Integration Guide¶

This guide explains how to integrate Slidefactory with N8N workflows using the official N8N community node package.

Overview¶

The n8n-nodes-slidefactory package provides native N8N integration for Slidefactory's presentation generation API. This allows you to:

• Generate presentations directly from N8N workflows
• Monitor presentation generation status
• Download and share generated presentations
• Manage templates programmatically
• Build automated presentation workflows

Installation¶

Prerequisites¶

1. N8N instance (cloud, self-hosted, or Docker)
2. Slidefactory instance with API access
3. API token with appropriate scopes

Install the Community Node¶

Option 1: Via N8N GUI (Recommended)¶

1. Open your N8N instance
2. Navigate to Settings → Community Nodes
3. Click Install a community node
4. Enter: n8n-nodes-slidefactory
5. Click Install
6. Wait for installation to complete
7. Refresh your browser

The Slidefactory node will now appear in your node palette.

Option 2: Via npm (Self-Hosted)¶

# In your N8N installation directory
cd ~/.n8n
npm install n8n-nodes-slidefactory

# Restart N8N
n8n start

Option 3: Docker¶

Add to your docker-compose.yml:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_CUSTOM_EXTENSIONS="/home/node/.n8n/custom"
    volumes:
      - ./n8n_data:/home/node/.n8n
    command: /bin/sh -c "npm install -g n8n-nodes-slidefactory && n8n start"

Or create a custom Dockerfile:

FROM n8nio/n8n
RUN npm install -g n8n-nodes-slidefactory

Configuration¶

Step 1: Generate API Token¶

Create an API token for N8N integration:

# Using Docker Compose
docker-compose exec web python -m cli users create-api-key <your-username> "N8N Integration" \
  --scopes "presentations:*,templates:read"

# Or using the slidefactory CLI wrapper
./slidefactory users create-api-key <your-username> "N8N Integration" \
  --scopes "presentations:*,templates:read"

Required Scopes: - presentations:generate - Generate presentations - presentations:read - Get status, list, download, share - presentations:delete - Delete presentations (optional) - templates:read - List and view templates

Recommended Scope Combinations: - Read-only: templates:read,presentations:read - Standard: templates:read,presentations:generate,presentations:read - Full access: presentations:*,templates:*

The command will output a token like:

API Key created successfully:
  Name: N8N Integration
  Token: sf_abc123def456ghi789jkl012mno345pqr
  Scopes: presentations:*, templates:read

⚠️ Important: Save this token securely. It won't be displayed again.

Step 2: Configure Credentials in N8N¶

1. Create a new workflow in N8N
2. Add a Slidefactory node to the canvas
3. Click on the Credential for Slidefactory API dropdown
4. Select Create New Credential
5. Fill in the credential form:

1. Click Save

N8N will automatically test the credentials by calling /api/presentations/list.

Step 3: Test the Integration¶

1. Configure the Slidefactory node:
2. Resource: Presentation
3. Operation: List
4. Click Execute Node
5. You should see a list of presentations (may be empty if none exist)

Usage Examples¶

Example 1: Simple Presentation Generation¶

Workflow:

Manual Trigger
  ↓
Slidefactory (Generate)
  ↓
Slidefactory (Get Status)

Slidefactory Generate Node Configuration:

{
  "resource": "presentation",
  "operation": "generate",
  "template_id": "1",
  "data": {
    "title": "Test Presentation",
    "date": "{{ $now.format('YYYY-MM-DD') }}",
    "content": "This is a test"
  }
}

Example 2: Automated Daily Reports¶

Workflow:

Schedule Trigger (Daily at 9 AM)
  ↓
HTTP Request (Fetch data from CRM)
  ↓
Code (Transform data)
  ↓
Slidefactory (Generate)
  ↓
Wait (30 seconds)
  ↓
Slidefactory (Get Status)
  ↓
IF (Status === 'finished')
  ↓ Yes
  Slidefactory (Download)
    ↓
    Email (Send to team)
  ↓ No
  Error (Notify admin)

Code Node (Data Transformation):

const salesData = $input.first().json;

return {
  json: {
    title: `Daily Sales Report - ${new Date().toLocaleDateString()}`,
    summary: {
      revenue: salesData.total_revenue,
      orders: salesData.order_count,
      avg_order: salesData.avg_order_value
    },
    top_products: salesData.products.slice(0, 5).map(p => ({
      name: p.name,
      units: p.units_sold,
      revenue: p.revenue
    }))
  }
};

Example 3: Webhook-Triggered Presentation¶

Workflow:

Webhook Trigger (POST /generate-presentation)
  ↓
Slidefactory (Generate)
  ↓
Slidefactory (Poll Status)
  ↓
Slidefactory (Share with 24h expiration)
  ↓
Webhook Response (Return share URL)

Webhook Trigger Configuration: - Method: POST - Path: /generate-presentation - Authentication: Basic Auth

Slidefactory Generate Node:

{
  "resource": "presentation",
  "operation": "generate",
  "template_id": "{{ $json.body.template_id }}",
  "data": "{{ $json.body.data }}",
  "additionalOptions": {
    "title": "{{ $json.body.title }}",
    "ai_provider": "openai",
    "ai_model": "gpt-4"
  }
}

Example 4: Batch Generation from Spreadsheet¶

Workflow:

Manual Trigger
  ↓
Google Sheets (Read rows)
  ↓
Loop Over Items
  ↓
  Slidefactory (Generate)
  ↓
  Wait (5 seconds - rate limiting)
  ↓
Merge (Collect process IDs)
  ↓
Wait (60 seconds - let all complete)
  ↓
Loop Over Process IDs
  ↓
  Slidefactory (Get Status)
  ↓
  IF (Status === 'finished')
    ↓
    Slidefactory (Download)
    ↓
    Google Drive (Upload)
  ↓
Slack (Notify completion)

Example 5: Template Management¶

Workflow:

Manual Trigger
  ↓
Slidefactory (List Templates)
  ↓
Code (Filter templates by criteria)
  ↓
Slidefactory (Get Placeholders for selected template)
  ↓
Code (Generate sample data matching schema)
  ↓
Slidefactory (Generate test presentation)

Advanced Features¶

Polling for Completion¶

Presentations are generated asynchronously. Use polling to wait for completion:

Method 1: Simple Wait + Check

Generate → Wait 30s → Get Status → IF finished

Method 2: Loop Until Complete

// Code node to check status
const status = $input.first().json.state;
if (status === 'finished' || status === 'error') {
  return {
    json: { complete: true, status }
  };
}
return {
  json: { complete: false, status }
};

Dynamic Template Selection¶

Load templates dynamically and select based on criteria:

// Code node after List Templates
const templates = $input.all();
const selectedTemplate = templates.find(t =>
  t.json.workflow_folder === 'reports' &&
  t.json.original_path.includes('sales')
);

return {
  json: {
    template_id: selectedTemplate.json.id,
    template_name: selectedTemplate.json.original_path
  }
};

Error Handling¶

Enable Continue On Fail for resilience:

1. Select the Slidefactory node
2. Go to Settings tab
3. Enable Continue On Fail
4. Add an error handling branch:

Slidefactory (Generate)
  ↓
IF (Error exists)
  ↓ Yes
  Slack (Notify admin)
  ↓
  Stop
  ↓ No
  Continue workflow

Rate Limiting¶

If generating many presentations, add delays:

Loop
  ↓
  Slidefactory (Generate)
  ↓
  Wait (2-5 seconds)

Recommended rates: - Light load: 2 seconds between requests - Heavy load: 5-10 seconds between requests

Using Result IDs¶

Instead of passing data directly, reference stored results:

// In Generate node
{
  "template_id": "1",
  "result_id": "{{ $json.result_uuid }}",  // UUID from previous workflow result
  "additionalOptions": {
    "title": "Presentation from stored result"
  }
}

API Reference¶

Presentation Operations¶

Template Operations¶

Troubleshooting¶

Common Issues¶

"Invalid API key" Error¶

Symptoms: 401 Unauthorized error

Solutions: 1. Verify API token is correct 2. Check token hasn't expired 3. Ensure Slidefactory URL is correct (no trailing slash) 4. Test API token manually:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-slidefactory.com/api/presentations/list

"Template not found" Error¶

Symptoms: 404 error when generating

Solutions: 1. Use List Templates operation to see available templates 2. Verify template_id is correct 3. Check API token has templates:read scope 4. Ensure template exists in database:

docker-compose exec web python -m cli templates list

Presentation Stuck in "pending"¶

Symptoms: Status never changes from "pending"

Solutions: 1. Check Celery workers are running:

docker-compose ps worker
docker-compose logs -f worker

docker-compose logs -f web

Download Returns Empty File¶

Symptoms: Downloaded file is 0 bytes or corrupted

Solutions: 1. Verify presentation state is finished before downloading 2. Check storage backend (MinIO/Azure) is accessible 3. Review Slidefactory logs for storage errors

Debug Mode¶

Enable verbose logging in N8N:

# Set environment variable
export N8N_LOG_LEVEL=debug

# Restart N8N
n8n start

Check N8N logs for detailed request/response info.

Best Practices¶

1. API Token Security¶

• ✅ Store tokens in N8N credentials (encrypted)
• ✅ Use minimal required scopes
• ✅ Rotate tokens periodically
• ✅ Create separate tokens per integration
• ❌ Never hardcode tokens in workflows
• ❌ Don't share tokens between environments

2. Resource Management¶

• Use Get Status before downloading to avoid unnecessary requests
• Delete old presentations periodically to save storage
• Cache template listings instead of fetching repeatedly
• Use Share URLs for external distribution instead of downloading

3. Error Handling¶

• Enable Continue On Fail for non-critical operations
• Add error notification nodes (Slack, Email)
• Log failures to external monitoring tools
• Implement retry logic for transient errors

4. Performance¶

• Poll status every 10-30 seconds (not every second)
• Add delays between batch operations
• Use Download only when needed (binary data is large)
• Leverage N8N's Binary Data mode for file handling

5. Workflow Organization¶

• Group related operations with Sticky Notes
• Name nodes descriptively ("Generate Sales Report" vs "Slidefactory")
• Use Set nodes to store intermediate values
• Document complex workflows with comments

Support¶

Resources¶

• Package README: /packages/n8n-nodes-slidefactory/README.md
• API Documentation: Check your Slidefactory instance at /docs
• User Management: DOCUMENTATION/USER_MANAGEMENT_QUICKREF.md
• Issue Tracker: GitHub Issues

Getting Help¶

1. Check this guide and package README first
2. Review N8N logs (N8N_LOG_LEVEL=debug)
3. Check Slidefactory logs (docker-compose logs)
4. Test API manually with curl/Postman
5. Open an issue with:
6. N8N version
7. Slidefactory version
8. Error messages
9. Workflow JSON (redact sensitive data)

Updates¶

Updating the Node Package¶

N8N Cloud¶

Updates are automatic when a new version is published to npm.

Self-Hosted¶

# In your N8N directory
npm update n8n-nodes-slidefactory

# Or specify version
npm install n8n-nodes-slidefactory@latest

# Restart N8N
n8n start

Docker¶

# Rebuild image
docker-compose build n8n

# Restart
docker-compose up -d n8n

Version Compatibility¶

Changelog¶

See packages/n8n-nodes-slidefactory/CHANGELOG.md for version history.

Questions or Issues?

Open an issue on GitHub or contact your Slidefactory administrator.