Skip to main content

MQTT Channels

Arvist services communicate over MQTT. This guide lists the topics used by each service and plugin.

Services​

Arvist Central​

  • Subscriptions
    • nvr/available - determines if nvr service is running
    • arvist/shipment/complete - when a shipment inspection is completed by Palletscan
    • arvist/shipment/unit-processing - when a unit is processing in Palletscan
    • arvist/shipment/unit-completed - when a unit is processed in Palletscan
    • arvist/shipment/error - an error occurred in Palletscan
  • Publications
    • arvist/update - updates services with mutated global settings, modules, and/or worker information
    • arvist/quality-stations/update - publishes full quality station data when stations are bulk upserted, including created, updated, and deleted stations
    • arvist/retake-snapshot - sends to retake base snapshot for Path Obstruction service
    • arvist/shipment-inspection/start - tells Palletscan to start inspection
    • arvist/shipment-inspection/stop - tells Palletscan to stop inspection (meaning no more units to observe)
    • arvist/shipment-inspection/images - sends images provided by user to Palletscan
    • arvist/shipment-inspection/post-id - update count with user-provided product identification
    • arvist/shipment-inspection/refresh - refresh current unit
    • arvist/shipment-inspection/cancel - cancel shipment inspection
    • arvist/shipment-inspection/issues - publishes when quality issues are detected during inspection
    • arvist/shipment-inspection/complete - publishes when a shipment inspection is completed

Event Service​

  • Subscriptions
    • nvr/events – consumes NVR event messages.
    • arvist/update – receives module configuration updates.
  • Publications
    • arvist/notifications – sends incident notifications.
    • arvist/incident/<module name> - sends incident data after incident is created.

Notification Service​

  • Subscriptions
    • arvist/notifications/# – processes notification requests for various notification types including email, SMS, and Slack.

R2 Uploader​

  • Subscriptions
    • arvist/upload – accepts upload requests for Cloudflare R2.

Pallet Scan Service​

  • Subscriptions
    • arvist/shipment-inspection/start
    • arvist/shipment-inspection/stop
    • arvist/shipment-inspection/images
    • arvist/shipment-inspection/post-id
    • arvist/shipment-inspection/refresh
    • arvist/shipment-inspection/cancel
    • nvr/available
  • Publications
    • arvist/shipment/unit-processing
    • arvist/shipment/unit-completed
    • arvist/shipment/complete
    • arvist/shipment/error

Training Data Collector​

  • Subscriptions
    • nvr/events – monitors events to collect training snapshots.

Plugins​

Asset Tracking​

  • Subscriptions
    • arvist/update – module configuration updates.
    • nvr/<zone>/person/active – per-zone person activity.

Path Obstruction​

  • Subscriptions
    • arvist/update – module configuration updates.
    • arvist/retake-snapshot – background refresh requests.
  • Publications
    • arvist/notifications – safety alerts.
    • arvist/incident/<module name> - sends incident data after incident is created.

Forklift Collision​

  • Subscriptions
    • arvist/update – module configuration updates.
    • nvr/events – live NVR events.
  • Publications
    • arvist/notifications – safety alerts.
    • arvist/incident/<module name> - sends incident data after incident is created.

Message Formats​

Quality Station Update​

Topic: arvist/quality-stations/update

Published when quality stations are bulk upserted. Contains full quality station objects and deleted station information.

Message Structure:

{
  "type": "quality_stations_bulk_update",
  "data": {
    "quality_stations": [
      {
        "id": 123,
        "area_id": 95,
        "area_name": "QS Station 1",
        "description": "Main inspection station",
        "quality_station_cameras": [
          {
            "side": "front",
            "quality_station_id": 123,
            "camera_id": 45,
            "camera_name": "Camera 1",
            "required": true
          }
        ],
        "zones": [...],
        "quality_station_specs": {...}
      }
    ],
    "deleted_stations": [
      {
        "area_id": 96,
        "area_name": "Deleted Station"
      }
    ],
    "timestamp": "2025-10-28T16:25:42.869Z"
  }
}

Fields:

  • quality_stations: Array of complete quality station objects with all fields including cameras, zones, and specifications
  • deleted_stations: Array of stations removed in this update, containing area_id and area_name
  • timestamp: ISO 8601 timestamp of when the update occurred

A single message is sent regardless of how many stations were created, updated, or deleted.

Shipment Inspection Start​

Topic: arvist/shipment-inspection/start

Published when a shipment inspection is started. Instructs Palletscan service to begin processing a shipment.

Message Structure:

{
  "shipment_id": 456,
  "extract_order_numbers": false
}

Fields:

  • shipment_id: Integer ID of the shipment to inspect
  • extract_order_numbers: Boolean flag indicating whether to extract order numbers from the shipment label during inspection (default: false)
    • When true: The system will attempt to extract order numbers from the physical shipment label using OCR/pattern matching
    • When false: Order numbers should already be associated with the shipment

Usage:

  • Published by Arvist Central when starting a shipment inspection via the API
  • Consumed by Palletscan service to initiate product counting and identification
  • The extract_order_numbers flag enables workflows where order information is scanned from labels after inspection begins

Shipment Inspection Issues​

Topic: arvist/shipment-inspection/issues

Published during shipment inspection when quality issues are detected. Issues can include damage reports or other quality concerns.

Message Structure (damage reports):

{
  "shipment_id": 1,
  "unit_id": "unit-001",
  "order_numbers": ["PO-12345"],
  "damage_reports": [
    {
      "unit_side": "front",
      "damages": [
        {
          "damage_type": "Torn Boxes",
          "damage_type_id": 3,
          "damage_description": "Multiple boxes show tearing",
          "box_quantity": 5
        }
      ]
    }
  ]
}

Message Structure (session issues):

{
  "shipment_id": 1,
  "unit_id": "unit-001",
  "order_numbers": ["PO-12345"],
  "session_issues": [
    {
      "id": 124,
      "issue_type": "wrong_load",
      "status": "open",
      "metadata": {
        "observed_order_numbers": ["PO-12345"]
      },
      "created_at": "2026-01-20T10:30:00.000Z",
      "updated_at": "2026-01-20T10:30:00.000Z"
    }
  ]
}

Fields:

  • shipment_id: Integer ID of the shipment being inspected
  • unit_id: String ID of the unit being inspected
  • order_numbers: Array of order/PO numbers associated with the shipment
  • damage_reports: Array of damage reports detected during inspection (published after image analysis)
    • unit_side: Side of unit where damage was detected ("front", "back", "left", "right", "top")
    • damages: Array of specific damage instances
      • damage_type: Description of damage type
      • damage_type_id: Integer ID of damage type
      • damage_description: Detailed description
      • box_quantity: Number of boxes affected (nullable)
  • session_issues: Array of non-damage session-level issues (published after unit completion)
    • id: Unique issue identifier
    • issue_type: Type of issue ("unidentified_product", "wrong_load", "no_order_numbers")
    • status: Issue status ("open", "resolved", "canceled")
    • description: Optional issue description
    • metadata: Additional issue-specific data
    • created_at/updated_at: ISO 8601 timestamps

When Published:

  • With damage_reports: After capturing and analyzing unit images, when damage detection completes
  • With session_issues: During unit completion, when non-damage issues are present (e.g., wrong load, missing order numbers)

Shipment Inspection Complete​

Topic: arvist/shipment-inspection/complete

Published when a shipment inspection is fully completed and ready for review.

Message Structure:

{
  "shipment": {
    "id": 456,
    "shipment_key": "SHP-2026-001",
    "type": "inbound",
    "status": "review",
    "order_numbers": ["PO-12345", "PO-67890"],
    "supplier": "Acme Corp",
    "created_at": "2026-01-20T08:00:00.000Z",
    "updated_at": "2026-01-20T10:30:00.000Z",
    "quality_station": {
      "id": 10,
      "area_id": 95,
      "area_name": "QS Station 1",
      "station_configuration": "dual_side_pallet"
    },
    "units": [
      {
        "id": "unit-001",
        "type": "pallet",
        "created_at": "2026-01-20T08:05:00.000Z",
        "sessions": [
          {
            "id": 789,
            "created_at": "2026-01-20T08:05:30.000Z",
            "updated_at": "2026-01-20T08:06:15.000Z",
            "images": [
              {
                "side": "front",
                "media": {
                  "id": 1234,
                  "source": "cloud",
                  "content": {
                    "image": {
                      "id": 5678,
                      "key": "shipments/2026/01/unit-001-front.jpg",
                      "filename": "unit-001-front.jpg",
                      "contentType": "image/jpeg",
                      "metadata": {}
                    }
                  }
                },
                "damages": [
                  {
                    "id": 101,
                    "type": "Torn Boxes",
                    "type_id": 3,
                    "category": "Packaging",
                    "category_type": "pallet",
                    "description": "Multiple boxes show tearing",
                    "damaged_box_qty": 5,
                    "created_at": "2026-01-20T08:06:00.000Z"
                  }
                ]
              }
            ],
            "issues": [
              {
                "id": 123,
                "issue_type": "damage",
                "status": "open",
                "created_at": "2026-01-20T08:06:00.000Z",
                "updated_at": "2026-01-20T08:06:00.000Z"
              }
            ]
          }
        ]
      }
    ],
    "line_items": [
      {
        "product_id": "PROD-123",
        "name": "Widget A",
        "sku": "WDG-A-001",
        "expected_quantity": 100,
        "actual_quantity": 98
      }
    ]
  }
}

Fields:

  • shipment: Complete shipment object
    • id: Shipment identifier
    • shipment_key: Unique shipment reference key
    • type: Shipment type ("inbound" or "outbound")
    • status: Shipment status (typically "review" when inspection completes)
    • order_numbers: Array of order/PO numbers
    • supplier: Supplier name
    • created_at/updated_at: ISO 8601 timestamps
    • quality_station: Station where inspection occurred
      • id: Quality station identifier
      • area_id: Area identifier
      • area_name: Name of the station area
      • station_configuration: Configuration type ("dual_side_pallet", "single_side_pallet", "full_pallet", etc.)
    • units: Array of inspected units
      • id: Unique unit identifier
      • type: Unit type ("pallet" or "product")
      • created_at: When unit was created
      • sessions: Array of inspection sessions for this unit (ordered by most recent first)
        • id: Session identifier
        • created_at/updated_at: Session timestamps
        • images: Array of captured images
          • side: Image side ("front", "back", "left", "right", "top")
          • media: Media object with storage details
            • id: Media record identifier
            • source: Storage source ("local" or "cloud")
            • content.image: Image content details
              • id: Content identifier
              • key: Storage key/path
              • filename: Original filename
              • contentType: MIME type
              • metadata: Additional metadata
          • damages: Array of detected damages on this image
            • id: Damage identifier
            • type: Damage type description
            • type_id: Damage type identifier
            • category: Damage category name
            • category_type: Category type ("pallet" or "product")
            • description: Detailed damage description
            • damaged_box_qty: Number of boxes affected (nullable)
            • created_at: When damage was recorded
        • issues: Array of session-level issues
          • id: Issue identifier
          • issue_type: Type of issue ("damage", "wrong_load", "no_order_numbers", "unidentified_product")
          • status: Issue status ("open", "resolved", "canceled")
          • description: Optional description
          • metadata: Additional issue-specific data
          • created_at/updated_at: Issue timestamps
          • resolved_at: When issue was resolved (nullable)
    • line_items: Product line items with expected vs actual quantities
      • product_id: Product identifier
      • name: Product name
      • sku: Product SKU
      • expected_quantity: Expected quantity
      • actual_quantity: Actual counted quantity

When Published:

  • After the operator has completed the inspection when all units have been inspected
  • Before the shipment status transitions to review state

Arvist Notifications​

Topic: arvist/notifications/#

The notifications service subscribes to this topic pattern to process various types of notifications. Multiple notification types are supported, including safetyAlert, shippingMismatch, shippingDamage, userActionLink, adminErrorLog, and custom.

Custom Notification Type​

Topic: arvist/notifications (or any subtopic under this prefix)

The custom notification type provides flexibility for sending arbitrary notifications with custom subject, content, and attachments.

Message Structure:

{
  "notificationType": "custom",
  "targets": {
    "email": ["user@example.com"],
    "sms": ["+1234567890"],
    "slack": ["channel-id"]
  },
  "data": {
    "subject": "Daily Report",
    "content": "Please find attached the daily report.",
    "attachments": [
      {
        "filename": "report.csv",
        "buffer": "base64-encoded-file-content",
        "contentType": "text/csv"
      }
    ]
  },
  "correlationId": "unique-tracking-id",
  "metadata": {
    "source": "reporting-service",
    "priority": "normal"
  }
}

Fields:

  • notificationType: Must be "custom" for custom notifications
  • targets: Object specifying notification recipients
    • email: Array of email addresses (optional)
    • sms: Array of phone numbers in E.164 format (optional)
    • slack: Array of Slack channel IDs (optional)
  • data: Custom notification content
    • subject: Email subject line (optional, defaults to "Custom Notification")
    • content: Notification body content (string or HTML string)
    • attachments: Array of file attachments (optional)
      • filename: Name of the attached file (optional)
      • buffer: Base64-encoded file content or raw Buffer (optional)
      • mediaUrl: URL to remote file instead of buffer (optional)
      • contentType: MIME type of the attachment (e.g., "text/csv", "application/pdf")
  • correlationId: Optional tracking identifier for logging and correlation
  • metadata: Optional additional metadata (any key-value pairs)

When Published:

  • By external services or custom integrations that need to send notifications
  • For scheduled reports, alerts, or custom workflows
  • When flexible notification content is required beyond predefined templates

Notes:

  • At least one target type must be specified (email, SMS, or Slack)
  • Attachments can be provided via buffer (base64-encoded) or mediaUrl (URL to file)
  • HTML content is supported in the content field for rich email formatting
  • The notification service automatically routes messages to the appropriate channels based on targets