ERP Connector Data Mapping Specification

Introduction

This document defines the data elements required to build an ERP Connector for MachineMetrics (MM). It serves as the authoritative mapping specification for integrating any ERP system with MM.

The document is intended for three audiences:

• ERP customers and IT teams – who need to understand what data must be provided.
• MachineMetrics internal staff – who configure and validate integrations.
• Automation agents (e.g., MCP or Cursor) – which use this document as structured guidance to generate queries, mappings, or API calls when building a connector.

---

How to Use This Document

Each section (Work Orders, Work Order Operations, Resources, Persons, Labor Tickets, Reasons) describes:

• Field Name – the ERP field to map.
• Description – its role in MM.
• Requirement – marked as ✅ Required (must be provided) or ⚪ Optional (enhances functionality).
• API Name – the equivalent MM field (in camelCase) for direct use in queries or API calls.
• Data Type – generic data type to guide schema mapping (string, integer, number, date, datetime, boolean).

For agents (MCP, Cursor, or LLM-based tools)

Use the API Name column when generating mappings or transformation code. The Required/Optional flags should be treated as constraints when validating integration completeness.

---

Required vs Optional Fields

• ✅ Required – Must be provided to enable core ERP-to-MM functionality.
• ⚪ Optional – Improves reporting, visibility, or flexibility but not strictly required for connector operation.

---

Data Synchronization Overview

ERP Connectors must support both:

• Historical load – imports work orders, operations, and other records up to a defined date to initialize MM.
• Incremental syncs – ongoing updates that only pull new or modified records using the updatedAt field (or ERP equivalent).

Different tables (e.g., Work Orders, Labor Tickets) may use different sync strategies, but all must include a reliable change-tracking field to avoid unnecessary data transfer.

For details on the required order in which to load this data, see the Load Sequence section at the end of the mapping specifications.

---

Work Orders

Work order data is the foundation of the ERP Connector. These fields define the unique identifier for each work order, its scheduling information, quantities, and part details. MachineMetrics uses this data to display accurate work order progress, calculate OEE, and tie machine activity back to ERP-defined jobs.

ERP Connector Guidance

• When possible, extract work orders and work order operations together. This ensures every operation is consistently linked with its parent work order and avoids "orphaned" operations.
• If your ERP has multiple scheduling or due date fields, choose the one that best represents the actual production schedule on the shop floor.
• In some ERPs, the customer name is not stored directly on the work order. In this case, it may need to be retrieved by joining the work order → sales order → customer master chain.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Work Order ID	Unique identifier for the work order	✅ Required	workOrderId	string	1.0
Lot	Refers to a material batch. If not used, default to an empty string.	✅ Required	lot	string	1.0
Split	Batch number if order split for staggered delivery. If not used, default to an empty string.	✅ Required	split	string	1.0
Sub	Refers to a child work order linked to a main work order, often used for sub-assemblies. If not used, default to an empty string.	✅ Required	sub	string	1.0
Description	Description of the work to be done.	⚪ Optional	description	string	1.0
Scheduled Start Date/Time	Planned start date/time.	✅ Required	scheduledStartDate	datetime	1.0
Scheduled End Date/Time	Planned end date/time.	✅ Required	scheduledEndDate	datetime	1.0
Due Date	Date work order must be completed.	✅ Required	dueDate	date	1.0
Closed Date	Actual date the work order was closed. May be null or blank until the work order is closed; an open or active work order will not have one. The connector must be able to pull this value once it is populated.	✅ Required	closedDate	date	1.0
Quantity Required	Planned production quantity.	✅ Required	quantityRequired	integer	1.0
Status	Current state of the work order. Must be mapped to one of the following enumerations: RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE (map ERP → MM enumerations).	✅ Required	status	string	1.0
Method / Job Type	Type of work.	⚪ Optional	method	string	1.0
Part Number	Part identifier.	✅ Required	partNumber	string	1.0
Part Revision	Part revision/version.	⚪ Optional	partRevision	string	1.0
Part Description	Text description of part.	⚪ Optional	partDescription	string	1.0
Part Family/Product Line	ERP grouping/category.	⚪ Optional	partFamily	string	Upcoming
Customer Name	ERP customer name.	⚪ Optional	customerName	string	Upcoming
Priority	ERP scheduling/priority indicator.	⚪ Optional	priority	integer	Upcoming
Updated At	Timestamp of last update, used for syncing data.	✅ Required	updatedAt	datetime	1.0

---

Work Order Operations

Operations (or sequences) are the steps required to complete a work order. Operation data enables MachineMetrics to show where in the process a job is, track sequence-specific performance, and capture cycle/setup times for OEE.

ERP Connector Guidance

• When extracting work orders and work order operations together, repeated fields linking work order operations to the work order (work order ID, lot, split, sub) are not required.
• Each operation must have a valid Resource ID (workcenter/machine) that exists in the ERP's resource list. This ensures MachineMetrics can tie production activity and labor tickets back to the correct machine or workcenter.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Work Order ID	Unique identifier for the work order	✅ Required	workOrderId	string	1.0
Lot	Refers to a material batch. If not used, default to an empty string.	✅ Required	lot	string	1.0
Split	Batch number if order split for staggered delivery. If not used, default to an empty string.	✅ Required	split	string	1.0
Sub	Refers to a child work order linked to a main work order, often used for sub-assemblies. If not used, default to an empty string.	✅ Required	sub	string	1.0
Sequence Number	Operation/sequence identifier.	✅ Required	sequenceNumber	integer	1.0
Resource ID	Workcenter or machine identifier.	✅ Required	resourceId	string	1.0
Start Quantity	The number of parts that have been completed on the WOO.	⚪ Optional	startQuantity	integer	1.0
Finish Quantity	The number of parts required to be made.	✅ Required	finishQuantity	integer	1.0
Expected Reject Rate	The % of parts expected to be bad when the job (operation) is done.	⚪ Optional	expectedRejectRate	number	1.0
Scheduled Start Date/Time	Planned start for operation.	✅ Required	scheduledStartDate	datetime	1.0
Scheduled End Date/Time	Planned end for operation.	✅ Required	scheduledEndDate	datetime	1.0
Closed Date	Actual date the operation completed.	⚪ Optional	closedDate	date	1.0
Cycle Time (ms)	Expected cycle time per part in milliseconds.	⚪ Optional	cycleTimeMs	integer	1.0
Setup Time (ms)	Expected setup time in milliseconds.	⚪ Optional	setupTimeMs	integer	1.0
Production Hourly Burden Rate	Hourly cost of running the operation in production.	⚪ Optional	productionBurdenRateHourly	number	1.0
Setup Hourly Burden Rate	Hourly cost to setup the operation.	⚪ Optional	setupBurdenRateHourly	number	1.0
Operation Type	Describes the type of work the operation represents.	⚪ Optional	operationType	string	1.0
Quantity per Part	Parts produced per cycle.	⚪ Optional	quantityPerPart	integer	1.0
Status	Operation status. Must be mapped to one of the following enumerations: RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE (map ERP → MM enumerations).	✅ Required	status	string	1.0
Updated At	Timestamp of last update, used for syncing data.	✅ Required	updatedAt	datetime	1.0

---

Labor Tickets

Labor tickets track operator activity such as clock-in/clock-out, production reporting, and scrap. They tie operator activity back to specific work orders, operations, resources, and people so MachineMetrics can attribute labor and production accurately.

For customers

At minimum, ensure that operator IDs and timestamps are accurate, as these fields drive labor tracking and traceability.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Work Order ID	Associated work order.	✅ Required	workOrderId	string	1.0
Lot	Refers to a material batch. If not used, default to an empty string.	✅ Required	lot	string	1.0
Split	Batch number if order split for staggered delivery. If not used, default to an empty string.	✅ Required	split	string	1.0
Sub	Refers to a child work order linked to a main work order, often used for sub-assemblies. If not used, default to an empty string.	✅ Required	sub	string	1.0
Operation Sequence Number	Associated operation/sequence.	✅ Required	sequenceNumber	integer	1.0
Resource ID	Resource where labor occurred.	✅ Required	resourceId	string	1.0
Person ID	Operator performing work.	✅ Required	personId	string	1.0
Labor Ticket ID	Unique identifier of the labor ticket from ERP.	✅ Required	laborTicketId	string	1.0
Transaction Date	Start date of the labor.	✅ Required	transactionDate	datetime	1.0
Clock-In Timestamp	Start time for labor.	✅ Required	clockIn	datetime	1.0
Clock-Out Timestamp	End time for labor.	⚪ Optional at clock-in / ✅ Required at clock-out	clockOut	datetime	1.0
Good Parts Produced	Number of good parts reported.	⚪ Optional	goodParts	integer	1.0
Bad Parts Produced	Number of scrapped/rejected parts.	⚪ Optional	badParts	integer	1.0
Type	Type of labor. Must be mapped to one of the following enumerations: SETUP, PRODUCTION, INDIRECT (map ERP → MM enumerations).	✅ Required	type	string	1.0
State	Describes the state of the labor ticket: OPEN, CLOSED (map ERP → MM enumerations).	✅ Required	state	string	1.0
Comment	Additional context about the work related to this ticket.	⚪ Optional	comment	string	1.0
Updated At	Timestamp of last update, used for syncing data.	✅ Required	updatedAt	datetime	1.0

---

Resources (Workcenters / Machines)

Resource data defines the machines, workcenters, or labor pools where work is performed. This ensures that MachineMetrics can tie machine signals to the correct ERP-defined resource.

For customers

Make sure your ERP's resource IDs match the naming convention used on your shop floor to avoid mapping confusion.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Resource ID	Workcenter or machine identifier.	✅ Required	resourceId	string	1.0
Name	A colloquial name for the resource, sometimes also just the resource ID.	⚪ Optional	name	string	1.0
Resource Group	Whether the resource is an individual machine or a group of machines.	⚪ Optional	isResourceGroup	boolean	1.0
Resource Description	Description of resource.	⚪ Optional	description	string	1.0
Type	Type of machine, such as Lathe or Mill.	⚪ Optional	type	string	1.0
Production Hourly Burden Rate	Hourly cost of running this operation in production.	⚪ Optional	productionBurdenRateHourly	number	1.0
Setup Hourly Burden Rate	Hourly cost to setup this operation.	⚪ Optional	setupBurdenRateHourly	number	1.0
Updated At	Timestamp of last update, used for syncs.	✅ Required	updatedAt	datetime	1.0

---

Persons (Operators / Employees)

Person data defines who is performing the work. Linking operators ensures labor tickets and performance metrics are attributed to the correct individual or team.

For customers

If your ERP uses employee numbers or short codes, share these consistently so they can be tied to MachineMetrics operator logins.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Person ID	Unique ERP operator/employee identifier.	✅ Required	personId	string	1.0
First Name	Employee/operator first name.	⚪ Optional	firstName	string	1.0
Last Name	Employee/operator last name.	⚪ Optional	lastName	string	1.0
Active Flag	Whether employee is active/terminated.	⚪ Optional	isActive	boolean	1.0
Updated At	Timestamp of last update, used for sync.	✅ Required	updatedAt	datetime	1.0

---

Reasons (Scrap Codes)

Reasons capture the standardized codes for scrap or reject reporting. When labor tickets report bad parts, MachineMetrics requires a valid reason code to categorize and sync this information with ERP.

For customers

Ensure ERP scrap/reject codes align with MM expectations to avoid mismatches during labor ticket submission.

Field Name	Description	Required/Optional	API Name	Data Type	SDK
Reason ID	Unique identifier for the reason code.	✅ Required	reasonId	string	1.0
Entity Type	Indicates the context the reason applies to, such as machine downtime or rejected parts (quality).	⚪ Optional	entityType	string	1.0
Category	Category of reason (scrap, downtime, etc.).	⚪ Optional	category	string	1.0
Code	Short ERP scrap/reject code.	⚪ Optional	code	string	1.0
Description	Full description of scrap/reject reason.	⚪ Optional	description	string	1.0
Updated At	Timestamp of last update, used for syncing reasons.	✅ Required	updatedAt	datetime	1.0

---

Load Sequence

When integrating with MachineMetrics, data must be loaded in a specific sequence to ensure that references between records (e.g., labor tickets pointing to employees, operations tied to work orders) remain valid.

note

This sequence is handled automatically when using the MachineMetrics ERP SDK. If you are not using the SDK, you must follow these rules manually to avoid broken references or sync errors.

1. Resources, Reason Codes, and Persons — Load master/lookup tables first. These provide the reference data needed for downstream records.
2. Work Orders and Operations — Next, load work orders together with their operations to establish parent–child relationships before transactions.
3. Labor Tickets — Finally, load labor tickets. These require work orders/operations, resource, and employee references to already exist.

---

Enumerations

• WORK ORDER STATUS: RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE
• WORK ORDER OPERATION STATUS: RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE
• LABOR TICKET TYPE: SETUP, PRODUCTION, INDIRECT
• LABOR TICKET STATUS: OPEN, CLOSED

---

Appendix: ERP Connector Rules (for LLMs and Implementers)

General Data Integration Rules

• RULE: Every entity (Work Order, Operation, Resource, Labor Ticket, Person, Reason) must include an updatedAt (or equivalent) field for incremental syncs.
• RULE: ERP Connector must support both historical data load (initial import) and incremental syncs (ongoing).
• RULE: Each table may use its own sync mechanism (e.g., last modified date, sys.id), but must guarantee incremental sync efficiency.
• RULE: Field enumerations must be mapped to MM ENUMERATIONS exactly (all caps). Example: Work Order Status → (RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE).
• RULE: Datetime strings should be in ISO 8601 format (e.g., 2025-04-17T03:29:00.000Z for UTC/Zulu time or, RECOMMENDED, 2025-04-17T03:29:00.000-05:00 for local time with offset).
• RULE: Date strings should be in ISO 8601, e.g. 2025-04-17T00:00:00.000-05:00 or 2025-04-17.

Work Orders

• RULE: Work Orders and Operations must be extracted as a flat file to ensure operations are always linked to their parent work orders.
• RULE: Work Orders must contain a unique Work Order ID.
• RULE: Due Date must be extracted consistently; if multiple ERP date fields exist, select the one representing shop floor schedule commitments.
• RULE: Customer Name may require joining Work Order → Sales Order → Customer Master. Always resolve to a human-readable name when possible.

Work Order Operations

• RULE: Every Operation must reference a valid parent Work Order.
• RULE: Each Operation must have a Sequence Number that uniquely identifies it within the Work Order.
• RULE: Resource IDs in operations must match valid ERP Resource table entries (workcenters/machines). Operations with unmapped resources should be excluded or flagged.
• RULE: Operation status must be mapped to MM ENUMERATIONS (RELEASED, NOT RELEASED, COMPLETED, CANCELED, ACTIVE).

Resources

• RULE: Every Resource ID in Operations or Labor Tickets must exist in the ERP Resource (Workcenter/Machine) table.
• RULE: Resource descriptions are optional, but if provided, they should match shop floor naming to avoid operator confusion.

Labor Tickets

• RULE: Labor Ticket Type must be mapped to MM ENUMERATIONS (SETUP, PRODUCTION, INDIRECT).
• RULE: Every Labor Ticket must reference a valid Person ID in the Persons table.
• RULE: Every SETUP or PRODUCTION type Labor Ticket must reference a valid Work Order, Operation, Resource, and Person.
• RULE: If bad parts are reported, a valid Reason Code must be supplied (see Reason Codes section).

Persons (Operators/Employees)

• RULE: Active Flag must be maintained to prevent assigning tickets to inactive employees.

Reason Codes

• RULE: If bad parts are reported in Labor Tickets, Reason Codes must be included.
• RULE: Reason IDs and Codes must be unique across the ERP.

Load Sequence

• RULE: Entities must be loaded in this order:
  1. Resources, Reason Codes, and Persons (lookup tables).
  2. Work Orders and Operations (parent/child relationships).
  3. Labor Tickets (dependent transactions).
• RULE: ERP SDK enforces this automatically. If not using SDK, ERP Connector must implement load sequencing manually.