@transai/connector-runner-hp-indigo

v0.3.0

Published

18 hours ago

A connector runner library for receiving job status messages from HP Indigo digital printing presses via JMF (Job Messaging Format) or webhook.

0High
0Medium
0Low

transai-automation-user

yourilefers

HP Indigo Connector Runner

A connector runner library for receiving job status messages from HP Indigo digital printing presses via JMF (Job Messaging Format) or webhook.

Note: This is a connector-runner library that runs within the connector-orchestrator process, not a standalone application.

Quick Start

Basic Configuration (Recommended)

{
  "callbackHost": "connector.example.com",
  "port": 3050,
  "webhookPath": "/hp-indigo/job-status",
  "jmf": {
    "enabled": true,
    "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1"
  }
}

What Happens

Connector starts on port 3050
Subscribes to HP Indigo via JMF
HP Indigo sends job notifications automatically
Data stored in <datasourceIdentifier>_job-status collection

Features

✅ Dual Mode Operation

JMF Subscription (automatic, standards-based)
Passive Webhook (fallback, manual configuration)

✅ Self-Healing

Automatic subscription health checks every 5 minutes
Auto-recovery if HP Indigo restarts or subscription fails
Startup cleanup of stale subscriptions

✅ Production-Ready

Graceful shutdown with proper JMF unsubscribe
5-second timeout protection
Handles crashes, SIGTERM, SIGINT via ConnectorSDK

✅ Flexible Parsing

Supports both XML and JSON message formats
Multiple field naming conventions (JobID/jobId/id)
Preserves all additional fields

Operation Modes

Mode 1: JMF Subscription (Recommended)

When to use: HP Indigo supports JMF protocol (DFE V12 and later)

Benefits:

Automatic registration - no manual printer configuration
Standards-based (CIP4 JMF)
Health monitoring with auto-heal
Proper lifecycle management

Configuration:

{
  callbackHost: 'connector.example.com', // Must be reachable by HP Indigo
  port: 3050,
  webhookPath: '/hp-indigo/job-status',
  jmf: {
    enabled: true,
    printerUrl: 'http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1',
    channelId: 'hp-indigo-channel-1' // Optional
  }
}

Mode 2: Passive Webhook (Fallback)

When to use: HP Indigo doesn't support JMF, or as fallback

Configuration:

{
  port: 3050,
  webhookPath: '/hp-indigo/job-status'
  // No JMF configuration
}

Setup: Manually configure HP Indigo to POST to:

http://<your-server-ip>:3050/hp-indigo/job-status

Configuration Reference

ConnectorConfig

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | callbackHost | string | Conditional | - | Externally reachable IP or hostname for webhook callback URL (required when jmf.enabled) | | port | number | No | 3050 | Port for webhook server | | webhookPath | string | No | /hp-indigo/job-status | Path for webhook endpoint | | jmf.enabled | boolean | No | false | Enable JMF subscription mode | | jmf.printerUrl | string | Conditional | - | HP Indigo JMF endpoint (required if jmf.enabled) | | jmf.channelId | string | No | channel-<timestamp> | Custom channel ID for subscription |

Example: Full Configuration

{
  "connector": {
    "identifier": "hp-indigo-prod",
    "type": "hp-indigo",
    "config": {
      "callbackHost": "connector.example.com",
      "port": 3050,
      "webhookPath": "/hp-indigo/job-status",
      "jmf": {
        "enabled": true,
        "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1",
        "channelId": "hp-indigo-channel-1"
      }
    }
  }
}

JMF Subscription Details

Lifecycle

┌─────────────────────────────────────────┐
│ STARTUP                                  │
├─────────────────────────────────────────┤
│ 1. Start webhook server (port 3050)     │
│ 2. Clean up stale subscriptions         │
│ 3. Send JMF Subscribe to HP Indigo      │
│ 4. Start health monitoring (every 5min) │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ OPERATION                                │
├─────────────────────────────────────────┤
│ • Receive job notifications              │
│ • Store in hp_indigo_job_status         │
│ • Track last notification time           │
│ • Health check every 5 minutes:          │
│   - Send JMF QueueStatus query           │
│   - Re-subscribe if unhealthy            │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ SHUTDOWN                                 │
├─────────────────────────────────────────┤
│ 1. Send JMF Unsubscribe (5s timeout)    │
│ 2. Stop health monitoring                │
│ 3. Close webhook server                  │
└─────────────────────────────────────────┘

Subscribe Message

<?xml version="1.0" encoding="UTF-8"?>
<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1"
     SenderID="TransAI-HP-Indigo-Connector"
     TimeStamp="2026-04-02T10:00:00Z"
     Version="1.4">
  <Query ID="query-123" Type="SubscriptionFilter">
    <SubscriptionFilter ChannelID="hp-indigo-channel-1" 
                       URL="http://<connector-host>:3050/hp-indigo/job-status">
      <MessageFilter MessageType="Signal">
        <SignalFilter SignalType="Status"/>
      </MessageFilter>
    </SubscriptionFilter>
  </Query>
</JMF>

Unsubscribe Message

<?xml version="1.0" encoding="UTF-8"?>
<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1"
     SenderID="TransAI-HP-Indigo-Connector"
     TimeStamp="2026-04-02T10:00:00Z"
     Version="1.4">
  <Command ID="cmd-123" Type="StopPersistentChannel">
    <StopPersistentChannel ChannelID="hp-indigo-channel-1"/>
  </Command>
</JMF>

Health Check Message

<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1">
  <Query Type="QueueStatus">
    <QueueFilter ChannelID="hp-indigo-channel-1"/>
  </Query>
</JMF>

Health Monitoring & Auto-Heal

The connector automatically monitors subscription health and recovers from failures.

How It Works

Every 5 minutes:

Send JMF QueueStatus query to HP Indigo
Check if subscription channel is active
If unhealthy → auto-heal (re-subscribe)
Fallback: check notification timestamps if JMF unavailable

Benefits:

✅ Instant failure detection (via JMF)
✅ Works even for idle printers
✅ Recovers from HP Indigo restarts
✅ Handles network interruptions
✅ No manual intervention needed

Scenarios Handled

| Scenario | Detection | Recovery | |----------|-----------|----------| | HP Indigo restarts | JMF QueueStatus fails | Auto-resubscribe | | Network interruption | JMF query fails + no data | Auto-resubscribe | | HP Indigo timeout | JMF indicates inactive | Auto-resubscribe | | Idle printer | JMF shows active | No action (healthy) |

Message Format

Incoming Messages

The connector accepts both XML and JSON:

XML Example:

<JobStatus>
  <JobID>12345</JobID>
  <JobName>Print Job Example</JobName>
  <Status>Completed</Status>
  <State>Finished</State>
  <Printer>HP Indigo 12000</Printer>
  <Owner>[email protected]</Owner>
  <Pages>100</Pages>
  <Sheets>25</Sheets>
  <Copies>4</Copies>
</JobStatus>

JSON Example:

{
  "jobId": "12345",
  "jobName": "Print Job Example",
  "status": "Completed",
  "state": "Finished",
  "printer": "HP Indigo 12000",
  "owner": "[email protected]",
  "pages": 100,
  "sheets": 25,
  "copies": 4
}

Stored Data

Messages are stored in ${datasourceIdentifier}_job-status collection (e.g., hp-indigo-prod_job-status) with these fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | jobId | string | Yes | Unique job identifier (key field) | | jobName | string | Yes | Job name | | jobStatus | string | Yes | Current status | | jobState | string | Yes | Current state | | timestamp | string | Yes | ISO timestamp (auto-generated) | | printer | string | No | Printer name/ID | | owner | string | No | Job owner | | pages | number | No | Number of pages | | sheets | number | No | Number of sheets | | copies | number | No | Number of copies |

Additional fields from the source are automatically preserved.

Network Setup

Example Network

HP Indigo: <printer-ip>:8080
Your Connector: <connector-host>:3050

Requirements

✅ Port 3050 open on connector server (firewall) ✅ Connector can reach HP Indigo JMF endpoint ✅ HP Indigo can reach connector webhook (for notifications)

Testing Connectivity

Test HP Indigo is reachable:

curl http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1

Test connector health endpoint:

curl http://<connector-host>:3050/health
# Should return: {"status":"ok"}

Logging

Normal Operation

[HP Indigo] Webhook server started on 0.0.0.0:3050
[HP Indigo] Listening for job status updates on /hp-indigo/job-status
[HP Indigo] Cleaning up any stale JMF subscriptions before starting...
[HP Indigo] No stale subscription found (expected on first start)
[HP Indigo JMF] Subscribing to printer at http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1
[HP Indigo JMF] Successfully subscribed with channel ID: hp-indigo-channel-1
[HP Indigo] JMF subscription established successfully
[HP Indigo] Starting subscription health monitoring

Health Check (Every 5 minutes)

[HP Indigo] Health check: Subscription active (verified via JMF)

Auto-Heal

[HP Indigo] JMF health check indicates subscription is not active - attempting to re-subscribe...
[HP Indigo] Subscription re-established successfully (auto-heal)

Shutdown

[HP Indigo] Initiating JMF unsubscribe...
[HP Indigo JMF] Unsubscribing channel hp-indigo-channel-1
[HP Indigo JMF] Successfully unsubscribed channel hp-indigo-channel-1
[HP Indigo] JMF subscription terminated successfully

Troubleshooting

Issue: Cannot connect to HP Indigo JMF endpoint

Test:

curl http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1

Solutions:

Check network connectivity: ping xxx.xxx.xxx.xx
Verify HP Indigo service is running
Check firewall on HP Indigo server
Verify JMF endpoint URL is correct

Issue: HP Indigo cannot reach webhook

Test from HP Indigo server:

curl http://<connector-host>:3050/health

Solutions:

Check connector is running
Check firewall on connector server (port 3050)
Verify network connectivity

Issue: JMF subscription fails

Check logs for: Failed to establish JMF subscription

Solutions:

Connector automatically falls back to passive webhook mode
Manually configure HP Indigo to POST to your webhook URL
Contact HP support for JMF documentation

Issue: Not receiving notifications

Check:

Is HP Indigo processing jobs?
Check connector-orchestrator logs for this connector's webhooks (set level to verbose)
Verify subscription is active: look for health check logs in orchestrator
Check auto-heal logs - may be re-subscribing
Verify connector is enabled in orchestrator configuration

Enable debug logging in orchestrator:

{
  "logging": {
    "level": "debug"
  }
}

Deployment

This connector-runner is deployed via the connector-orchestrator, not as a standalone application.

How to Deploy

Build the library:

npm exec nx build connector-runner-hp-indigo

Add connector configuration to connector-orchestrator:

{
  "identifier": "hp-indigo-prod",
  "connectorType": "hp-indigo",
  "tenantIdentifier": "your-tenant",
  "name": "HP Indigo Production",
  "enabled": true,
   "config": {
     "port": 3050,
     "webhookPath": "/hp-indigo/job-status",
     "jmf": {
       "enabled": true,
       "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1",
       "channelId": "hp-indigo-channel-1"
     }
   }
}

Configure network access on the host running connector-orchestrator:
- Allow incoming TCP on port 3050 (for HP Indigo notifications)
- Allow outgoing connections to HP Indigo JMF endpoint
Start/restart connector-orchestrator
- Orchestrator will load and run this connector-runner
- Monitor orchestrator logs for HP Indigo connector startup

Network Requirements

Port 3050 must be accessible on the orchestrator host (from HP Indigo network)
Runs within orchestrator process (no separate deployment)
Uses orchestrator's logging infrastructure
Works wherever orchestrator runs (cloud/on-prem/VM/bare metal)

Advanced Features

Startup Cleanup

Prevents duplicate subscriptions by unsubscribing stale channels on startup:

// On startup, before subscribing:
1. Attempt to unsubscribe (cleanup old subscription)
2. Subscribe with fresh subscription
3. Start health monitoring

This handles crashes where previous instance didn't cleanly unsubscribe.

Health Monitoring

Primary Check (JMF-based):

Sends JMF QueueStatus query every 5 minutes
Verifies subscription channel is active
Instant detection, works for idle printers

Fallback Check (Data-based):

If JMF query fails, checks notification timestamps
Triggers re-subscribe if no data for 15+ minutes
Graceful degradation if JMF unsupported

Graceful Shutdown

ConnectorSDK handles all signals (SIGTERM, SIGINT, uncaughtException). On shutdown:

1. Stop() called by SDK
2. JMF unsubscribe sent (max 5 seconds)
3. Stop health monitoring
4. Close webhook server
5. Exit cleanly

Unsubscribe has 5-second timeout to prevent hanging.

Message Capture

All fields are captured and preserved:

Standard Fields (typed):

jobId, jobName, jobStatus, jobState
timestamp (auto-generated)
printer, owner, pages, sheets, copies

Additional Fields (dynamic):

All other fields from the source message are preserved
Supports both PascalCase and camelCase
Handles XML attributes and nested elements

Endpoints

| Path | Method | Description | |------|--------|-------------| | /hp-indigo/job-status | POST | Receives job status notifications | | /health | GET | Health check (returns {"status":"ok"}) |

Development

Build Library

npm exec nx build connector-runner-hp-indigo

Run Tests

npm exec nx test connector-runner-hp-indigo

Lint Code

npm exec nx lint connector-runner-hp-indigo

Testing in Connector-Orchestrator

To test this connector-runner:

Build the library: npm exec nx build connector-runner-hp-indigo
Configure connector in connector-orchestrator
Start connector-orchestrator
Monitor logs for HP Indigo connector startup and subscription

Architecture

┌─────────────────┐
│  HP Indigo DFE  │
│  xxx.xxx.xxx.xx │
└────────┬────────┘
         │ JMF Subscribe/Health Check
         ↓
┌─────────────────┐
│  JMF Client     │  - Subscription management
│                 │  - Health monitoring
└────────┬────────┘  - Auto-heal
         │
         │ Callbacks
         ↓
┌─────────────────┐
│ Webhook Server  │  - HTTP server (Express)
│  Port 3050      │  - XML/JSON parsing
└────────┬────────┘  - Data storage
         │
         ↓ Notifications
┌─────────────────┐
│  HP Indigo      │  ← Job status updates
│  Printer        │
└─────────────────┘

Files

lib/connector-runner-hp-indigo.ts - Main connector class implementing ConnectorRuntimeSDK
jmf-client.ts - JMF protocol client (subscribe/unsubscribe/health)
webhook-server.ts - Express HTTP webhook server
types.ts - TypeScript interfaces and configuration types
index.ts - Public API exports

Standards & References

JMF: CIP4 Job Messaging Format for print industry
CIP4: International Cooperation for Integration of Processes
HP Indigo: Digital printing press messaging

Guarantees

✅ JMF unsubscribe will be called on every shutdown (via ConnectorSDK) ✅ Maximum 5-second delay during shutdown (won't hang) ✅ Health checks every 5 minutes using JMF protocol ✅ Auto-recovery from subscription failures ✅ Startup cleanup prevents duplicate subscriptions ✅ Crash-resilient - recovers gracefully on restart ✅ Graceful fallback to passive mode if JMF unavailable ✅ Production-tested - follows xod-core conventions

License

Part of the xod-core platform.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

HP Indigo Connector Runner

Quick Start

Basic Configuration (Recommended)

What Happens

Features

Operation Modes

Mode 1: JMF Subscription (Recommended)

Mode 2: Passive Webhook (Fallback)

Configuration Reference

ConnectorConfig

Example: Full Configuration

JMF Subscription Details

Lifecycle

Subscribe Message

Unsubscribe Message

Health Check Message

Health Monitoring & Auto-Heal

How It Works

Scenarios Handled

Message Format

Incoming Messages

Stored Data

Network Setup

Example Network

Requirements

Testing Connectivity

Logging

Normal Operation

Health Check (Every 5 minutes)

Auto-Heal

Shutdown

Troubleshooting

Issue: Cannot connect to HP Indigo JMF endpoint

Issue: HP Indigo cannot reach webhook

Issue: JMF subscription fails

Issue: Not receiving notifications

Deployment

How to Deploy

Network Requirements

Advanced Features

Startup Cleanup

Health Monitoring

Graceful Shutdown

Message Capture

Endpoints

Development

Build Library

Run Tests

Lint Code

Testing in Connector-Orchestrator

Architecture

Files

Standards & References

Links

Guarantees

License