Creating Your Own Connector

MachineMetrics staff — MM infrastructure deploy

Deploying connectors to MachineMetrics-managed infrastructure (CircleCI, ECR, edge rollout) is documented in internal Confluence, not on this public site.

Who this guide is for

Self-hosted developers — scaffold, implement, then run the connector on a laptop, VM, or server you control. To deploy on MachineMetrics infrastructure, contact your Solution Delivery Manager.

MachineMetrics ERP connectors integrate your ERP with the platform using the @machinemetrics/mm-erp-sdk and the mmdev CLI. This guide walks you through scaffolding a skeletal connector project, implementing against the SDK, and deploying on infrastructure you control.

A skeletal connector will provide you with documentation of how a full connector is created. Once constructed, you must familiarize yourself with the particulars of your ERP (APIs and schemas, authentication paths, which entities matter, how the shop uses the ERP, sample payloads, network access, sandbox credentials, and internal documentation exports) and the needs of your organization to complete the connector.

Work through this guide in sidebar order — Scaffold → Deploy → Implementation Patterns. Remaining topics are referred to in these pages. Read through this page before starting.

Scaffold and Deploy the Skeletal connector

First create the skeletal ERP connector by following the Scaffold and Deploy topics. This will assert that you have the required credentials on the MachineMetrics side to complete the project, access to the related documentation, and the ability to deploy. It is advised to read over the Implementation Patterns section before completing the skeletal ERP to familiarize yourself with all relevant concepts.

Once complete, run the skeletal connector on a laptop, VM, or server you control for verification.

Phase	Goal	Typical contents
Skeletal / POC	Prove the repo builds, config loads, logging works, and deploy path succeeds	Default or stub sync paths, minimal env config, MMConnectorLogger wired; deploy per Deploy
ERP-specific	Replace stubs with real queries/API calls, mappings, and error handling	Driven by ERP references and connector requirements; integration mode per Implementation Patterns

Implementation Patterns

The generic-erp-connector template from which the skeletal connector is created is transport-agnostic. It does not know the ERPs BAQs, REST resources, table names, labor rules, or whether ShopPulse events should write back to the ERP. That knowledge comes from discovery—often iteratively, and after the thin connector is already building and deploying as a POC. The Implementation Patterns page is dedicated to this topic.

Documentation path

This developer guide is the roadmap for scaffold/deploy and implementation. Implementation detail and related documentation lives in your connector project — not on these pages — and that documentation is created automatically when you scaffold; in addition, documentation is provided within the SDK:

• From the template: README.md, CONNECTOR-GUIDE.md, and the connector scaffold.
• From the SDK: reference docs such as CONNECTOR_SDK_UTILITIES.md and MM_ENTITY_KEYS_REFERENCE.md.

Treat the in-repo chain as the canonical guide for implementation of the full connector. The diagram below shows how this site relates to those documentation layers:

Developer site (this guide)
        │
        ▼
Generated connector repo — README.md, CONNECTOR-GUIDE.md
        │
        ▼
@machinemetrics/mm-erp-sdk — CONNECTOR_SDK_UTILITIES.md, MM_ENTITY_KEYS_REFERENCE.md

Using an AI assistant

If you use an AI coding assistant, give it this page and your connector project. Follow the Documentation path and the full sidebar order above; do not ask the assistant to improvise steps.

Expect to handle authentication (mmdev login), approve commits and pushes (if you use a remote repository), and supply ERP references and connector requirements (sandbox credentials, sample API requests). Do not paste production secrets into the assistant.

Once the scaffolding is complete, provide ERP references and connector requirements explicitly (see ERP discovery checklist).

Safety and access rules for assistants

An assistant helping with this guide should follow these rules throughout scaffold, deploy of the skeletal connector, and implementation of the full connector:

1. Never create accounts. Do not sign up for or register accounts on GitHub, MachineMetrics, npm, or any other service. If the developer does not already have required access, explain what they need and stop — do not attempt to create or configure accounts on their behalf.

2. Gate external actions behind explicit approval. Before any step that creates resources, authenticates, or sends data outside the local machine, describe exactly what will happen and wait for confirmation. This includes creating or cloning remote repositories, running the mmdev installer or mmdev login / oauth dev-init / mmdev create, and pushing commits to a remote.

3. Local work may proceed with notice. File edits, npm install, and npm run build on the developer’s machine do not require approval first — but the assistant should still say what it is doing.

4. Browser and manual steps. Provide the URL and instructions, then ask the developer to confirm when the step is done before continuing.

5. When access or artifacts are missing, direct the developer to When you lack access and Scaffold fallbacks (delegated mmdev create, project archive, or manual template copy). Ask them to supply ERP references and connector requirements or obtain them from their MachineMetrics contact — do not guess ERP details or skip blocked steps. Similarly, do not invent ERP field names or endpoints.

Prerequisites (overview)

Requirement	Notes
MachineMetrics account	Required for primary mmdev scaffold path
Network access	CLI installer and API endpoints
Docker	Advisable for repeatable deploy; optional if running directly with Node on the host
Node.js	Required to build and run the connector
Private repo access	MachineMetrics GitHub org repos are often restricted — contact your MM contact or use scaffold fallbacks

When you lack access

Contact your MachineMetrics contact (Solution Delivery Manager, customer success, or implementation lead) when you cannot complete a step in this guide — for example mmdev authentication or access to private GitHub repositories and template sources.

Common options for what they can provide include:

• Running mmdev create on your behalf and handing you a repository or project archive
• Sharing copies of artifacts (scaffold trees, reference snippets, configuration examples) when direct GitHub org access is not available

See Scaffold — Appendix: Scaffold fallbacks for the documented self-service and delegated paths.