MM ERP Connector SDK

A TypeScript SDK for building ERP connectors that integrate with MachineMetrics' data synchronization platform.

Overview

This SDK provides the core infrastructure for:

• Data Sync Service: Automated job scheduling for bidirectional ERP data synchronization
• ERP Connector Interface: Standardized interface for implementing ERP connectors
• MM API Integration: Client for interacting with MachineMetrics APIs
• Utility Functions: Common data transformation and HTTP utilities

Quick Start

1. Install the SDK

npm install mm-erp-sdk

2. Implement an ERP Connector

import {
  IERPConnector,
  IERPLaborTicketHandler,
  ERPObjType,
  MMReceiveLaborTicket,
  ApplicationInitializer,
  runDataSyncService,
} from "mm-erp-sdk";

export default class MyERPConnector
  implements IERPConnector, IERPLaborTicketHandler
{
  get type(): string {
    return "JOB_BOSS"; // replace with your ERP type
  }

  async startUp(): Promise<void> {
    try {
      await ApplicationInitializer.initialize();
      await runDataSyncService();
    } catch (error) {
      console.error("Startup failed:", error);
      process.exitCode = 1;
    }
  }

  async syncFromERP(): Promise<void> {
    // Implement your data sync from ERP logic
  }

  async syncToERP(): Promise<void> {
    // Implement your data sync to ERP logic
  }

  async createLaborTicketInERP(
    laborTicket: MMReceiveLaborTicket
  ): Promise<{ laborTicket: MMReceiveLaborTicket; erpUid: string }> {
    // Implement labor ticket creation
  }

  async updateLaborTicketInERP(
    laborTicket: MMReceiveLaborTicket
  ): Promise<MMReceiveLaborTicket> {
    // Implement labor ticket updates
  }

  // Implement other required methods...
}

3. Start the Data Sync Service

import MyERPConnector from "./my-erp-connector";

const connector = new MyERPConnector();
await connector.startUp();

Data Sync Jobs

The SDK includes automated jobs that run on configurable intervals:

• from-erp: Syncs data from ERP to MachineMetrics
• to-erp: Syncs labor tickets from MachineMetrics to ERP
• retry-failed-labor-tickets: Retries failed labor ticket operations
• clean-up-expired-cache: Maintains cache hygiene

Configure job intervals via environment variables:

FROM_ERP_INTERVAL="5m"
TO_ERP_INTERVAL="1m"
RETRY_LABOR_TICKETS_INTERVAL="10m"
CACHE_EXPIRATION_CHECK_INTERVAL="1h"

Environment Configuration

Set these environment variables for your connector:

# Required
ERP_SYSTEM="job-boss"
MM_MAPPING_SERVICE_URL="https://erp-api.svc.machinemetrics.com"
MM_MAPPING_AUTH_SERVICE_URL="https://api.machinemetrics.com"
MM_API_AUTH_TOKEN="your-auth-token"

# SQL Server (if using SQL Server ERP)
SQL_SERVER_HOST="localhost"
SQL_SERVER_DATABASE="your-db"
SQL_SERVER_USERNAME="username"
SQL_SERVER_PASSWORD="password"

# Logging
LOG_LEVEL="info"

Logging Reliability

• The SDK logger now captures rotate/write transport failures internally, but callers should still treat logging as best-effort. If you manage your own in-process scheduler (e.g., not using Bree), wrap any job.isRunning = true flags and subsequent logger.* calls in a try/finally block so the scheduler state clears even if logging throws.
• Bree-based connectors inherit process isolation, but custom schedulers run inside a single event loop. Always reset locks/timers inside finally clauses to avoid getting stuck when a synchronous dependency (logging, metrics, etc.) fails mid-cycle.

API Reference

Core Interfaces

• IERPConnector: Main connector interface
• IERPLaborTicketHandler: Labor ticket operations interface

Utilities

• ApplicationInitializer: SDK initialization
• runDataSyncService: Start automated sync jobs
• StandardProcessDrivers: Common sync operations

Services

• SqlServerService: SQL Server integration
• RestAPIService: HTTP API client
• MMApiClient: MachineMetrics API client

For detailed API documentation, see the TypeScript definitions.

Labor ticket updates: processing only closed tickets

If your connector only wants to act on labor tickets when they are closed, you can instruct the SDK to request only closed tickets from the MM labor ticket export/updates API by passing onlyClosed: true when initiating the sync:

import { StandardProcessDrivers } from "mm-erp-sdk";

await StandardProcessDrivers.syncLaborTicketsToERP(this.type, this, {
  onlyClosed: true,
});

This forwards onlyClosed=true to:

• /erp/v1/labor-tickets/export/updates