Connectors Guide

Deploy on-premise agents to securely connect your local network resources — printers, file systems, and databases — to the DataMagik cloud platform.

Table of Contents

1. Overview
2. Sites
3. Connector Setup
4. Activation Flow
5. WebSocket Connectivity
6. Managing Connectors
7. Rolling Updates
8. High Availability
9. Best Practices

1. Overview

Connectors are lightweight on-premise agents that run on your local network. They provide a secure bridge between DataMagik's cloud platform and your local resources such as printers, file systems, and databases.

Key Features:

• Secure Communication — WebSocket connection with API key authentication
• Site-Based Grouping — Organize connectors by physical location
• Rolling Updates — Update connector software without downtime
• High Availability — Multiple connectors per site for automatic failover
• Heartbeat Monitoring — Real-time online/offline status tracking

2. Sites

Sites represent physical locations (e.g., "Detroit Plant", "Warehouse B") that group related connectors.

Why Use Sites?

• Group connectors at the same physical location
• Printers are assigned to sites, enabling failover across connectors
• Rolling updates are managed per site
• Provides logical organization for multi-location deployments

Managing Sites

Navigate to Connectors → Sites to create, edit, or delete sites.

Note: A site cannot be deleted if it has connectors or printers assigned to it.

3. Connector Setup

Step 1: Create a Connector

In the DataMagik dashboard, create a new connector:

1. Navigate to Connectors
2. Click Add Connector
3. Enter a name and assign to a site
4. The system generates a provisioning token (valid for 7 days)

Step 2: Install the Connector Agent

Download and install the connector binary on your on-premise machine. The latest version is always available from the DataMagik platform.

Step 3: Activate

Run the connector agent and provide the provisioning token. The agent will:

1. Send its device information (IP address, MAC address, hostname)
2. Receive a permanent API key for runtime communication
3. Establish a WebSocket connection to DataMagik

4. Activation Flow

Security Notes:

• Provisioning tokens expire after 7 days and are single-use
• Runtime API keys are hashed in the database — the plaintext is shown only once at activation
• All communication uses encrypted WebSocket connections

5. WebSocket Connectivity

Once activated, the connector maintains a persistent WebSocket connection to DataMagik.

What the WebSocket Handles

• Print Jobs — Receives print job commands and reports completion/failure
• File Operations — Executes file system operations (list, read, write, etc.)
• IPP Probing — Discovers network printers on the local network
• Heartbeats — Maintains online status and last-seen timestamps

Connection Status

6. Managing Connectors

Connector Details

Each connector displays:

• Name, status, and last heartbeat time
• Device information (IP, hostname, MAC address)
• Current software version
• Assigned site
• Whether printing is enabled

Editing a Connector

You can update:

• Connector name
• Site assignment
• Printing enabled/disabled
• Update channel (stable, beta, or canary)

Regenerating Tokens

If a connector's API key is compromised, generate a new token from the connector settings. The old key is immediately invalidated.

7. Rolling Updates

Update connector software across a site without downtime.

How It Works

1. Trigger Update — Admin selects a site and target version
2. Coordination — Each connector checks for updates and downloads the new binary
3. Self-Update — Connectors apply the update and restart
4. Completion — Each connector reports back with success or failure

Update Progress

Track the update status for each connector in the site:

Updates can be cancelled mid-progress to prevent remaining connectors from starting.

8. High Availability

Deploy multiple connectors at a site for automatic failover:

• Print Job Failover — If a connector fails to print, the job is automatically routed to another connector at the same site
• Stale Lock Recovery — Jobs locked for more than 5 minutes are automatically released for retry
• Connector Tracking — The system tracks which connectors have been tried to avoid re-attempting failed routes

9. Best Practices

Deployment

• Deploy at least 2 connectors per site — Ensures availability if one goes offline
• Use descriptive site names — Match physical locations (e.g., "Building A - Floor 2")
• Use the stable update channel — Unless you need to test pre-release features

Security

• Store API keys securely — They are shown only once at activation
• Monitor heartbeats — Investigate connectors that go offline unexpectedly
• Use network segmentation — Place connectors on the same network as the resources they access

Maintenance

• Keep connectors updated — Use rolling updates to stay on the latest version
• Review connector status regularly — Ensure all connectors are online and healthy
• Remove unused connectors — Delete connectors that are no longer in service