@machinemetrics/mm-erp-sdk 0.3.0-beta.0 → 0.3.0-beta.1

package/src/utils/error-formatter.ts

@@ -0,0 +1,205 @@
+/**
+ * Error formatter utility for standardizing error messages across connectors
+ * Extracts human-readable messages from various error types (axios, custom errors, etc.)
+ */
+
+export interface FormattedError {
+  message: string;
+  code: string;
+  httpStatus?: number;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Extract meaningful error message from various error types
+ */
+export function formatError(error: any): FormattedError {
+  if (!error) {
+    return {
+      message: 'Unknown error occurred',
+      code: 'UNKNOWN_ERROR',
+    };
+  }
+
+  // Handle axios errors FIRST (before checking for FormattedError)
+  // because axios errors also have message and code properties
+  if (error.isAxiosError || error.name === 'AxiosError') {
+    return formatAxiosError(error);
+  }
+
+  // If it's already a FormattedError, return as-is
+  // Check for httpStatus or metadata to distinguish from axios errors
+  if (error.message && error.code && typeof error.message === 'string' && typeof error.code === 'string' && !error.config) {
+    return error as FormattedError;
+  }
+
+  // Handle standard Error objects
+  if (error instanceof Error) {
+    return {
+      message: error.message || 'An error occurred',
+      code: 'ERROR',
+      metadata: {
+        name: error.name,
+      },
+    };
+  }
+
+  // Handle string errors
+  if (typeof error === 'string') {
+    return {
+      message: error,
+      code: 'ERROR',
+    };
+  }
+
+  // Last resort: try to extract any useful info
+  const message = error.message || error.toString?.() || 'Unknown error occurred';
+  return {
+    message: typeof message === 'string' ? message : JSON.stringify(message),
+    code: error.code || 'UNKNOWN_ERROR',
+  };
+}
+
+/**
+ * Format axios-specific errors with detailed context
+ */
+function formatAxiosError(error: any): FormattedError {
+  const httpStatus = error.response?.status;
+  const method = error.config?.method?.toUpperCase();
+  const url = error.config?.url;
+  
+  // First check if connector already extracted the message
+  let message = error._extractedMessage;
+  
+  // If not, try to extract from response data
+  if (!message) {
+    const extractedMessage = extractErrorMessage(error.response?.data);
+    message = extractedMessage || error.response?.statusText || error.message || 'Request failed';
+  }
+
+  // Determine error code based on status
+  const code = categorizeHttpError(httpStatus);
+
+  const metadata: Record<string, any> = {
+    method,
+    url,
+  };
+
+  // Add additional context for specific error types
+  if (httpStatus === 401 || httpStatus === 403) {
+    metadata.hint = 'Check authentication credentials';
+  } else if (httpStatus === 404) {
+    metadata.hint = 'Resource not found - check endpoint URL';
+  } else if (httpStatus && httpStatus >= 500) {
+    metadata.hint = 'ERP system may be temporarily unavailable';
+  }
+
+  return {
+    message,
+    code,
+    httpStatus,
+    metadata,
+  };
+}
+
+/**
+ * Extract meaningful error message from response data
+ * Handles various ERP-specific response formats
+ */
+function extractErrorMessage(data: any): string | null {
+  if (!data) return null;
+
+  // Common error message fields across different ERPs
+  const possibleFields = [
+    'ErrorMessage',        // Epicor
+    'error.message',       // Common REST format
+    'error',               // Simple format
+    'Message',             // .NET style
+    'message',             // JavaScript style
+    'errorMessage',        // Camel case
+    'error_message',       // Snake case
+    'errors[0].message',   // Array of errors
+    'title',               // Problem details format
+    'detail',              // Problem details format
+  ];
+
+  for (const field of possibleFields) {
+    const value = getNestedValue(data, field);
+    if (value && typeof value === 'string') {
+      return value;
+    }
+  }
+
+  // If data is a string, return it
+  if (typeof data === 'string') {
+    // Try to parse as JSON first
+    try {
+      const parsed = JSON.parse(data);
+      return extractErrorMessage(parsed);
+    } catch {
+      return data;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj: any, path: string): any {
+  const parts = path.split('.');
+  let current = obj;
+
+  for (const part of parts) {
+    // Handle array notation like 'errors[0]'
+    const arrayMatch = part.match(/(\w+)\[(\d+)\]/);
+    if (arrayMatch) {
+      const [, key, index] = arrayMatch;
+      current = current?.[key]?.[parseInt(index, 10)];
+    } else {
+      current = current?.[part];
+    }
+
+    if (current === undefined || current === null) {
+      return null;
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Categorize HTTP errors into standard codes
+ */
+function categorizeHttpError(status?: number): string {
+  if (!status) return 'NETWORK_ERROR';
+
+  if (status === 400) return 'VALIDATION_ERROR';
+  if (status === 401) return 'AUTHENTICATION_ERROR';
+  if (status === 403) return 'AUTHORIZATION_ERROR';
+  if (status === 404) return 'NOT_FOUND';
+  if (status === 409) return 'CONFLICT';
+  if (status === 422) return 'VALIDATION_ERROR';
+  if (status === 429) return 'RATE_LIMIT';
+  if (status >= 500) return 'ERP_SERVER_ERROR';
+  if (status >= 400) return 'CLIENT_ERROR';
+
+  return 'HTTP_ERROR';
+}
+
+/**
+ * Format error for logging (shorter, cleaner version)
+ */
+export function formatErrorForLogging(error: any): string {
+  const formatted = formatError(error);
+  
+  let message = `[${formatted.code}] ${formatted.message}`;
+  
+  if (formatted.httpStatus) {
+    message = `[${formatted.httpStatus}] ${message}`;
+  }
+  
+  return message;
+}
+

package/src/utils/http-client.ts

@@ -64,9 +64,10 @@ class AxiosClient implements HTTPClient {
    *   It can be convenient to set `baseURL` for an instance of axios to pass relative URLs to methods of that instance.
    */
   constructor(baseUrl: string, retryAttempts: number) {
+    const timeout = parseInt(process.env.MM_API_TIMEOUT || "30000");
     this.client = axios.create({
       baseURL: baseUrl,
-      timeout: 30000,
+      timeout: timeout,
       headers: {
         "Content-Type": "application/json",
       },
@@ -108,7 +109,7 @@ class AxiosClient implements HTTPClient {
       params: config.params,
       signal: controller.signal,
     };
-// MLW TODO
+
     logger.info("HTTP request starting", { 
       url: config.url, 
       method: config.method, 
@@ -127,10 +128,8 @@ class AxiosClient implements HTTPClient {
     try {
       for (let attempt = 0; attempt <= this.retryAttempts; attempt++) {
         try {
-          // MLW TODO
           logger.info(`HTTP request attempt ${attempt + 1}/${this.retryAttempts + 1}`);
           const response = await this.client.request<T>(axiosConfig);
-          // MLW TODO
           logger.info("HTTP request succeeded", { status: response.status });
           return {
             data: response.data,

package/src/utils/index.ts

@@ -17,11 +17,6 @@ export {
 export { getTimezoneOffsetAndPersist } from "./time-utils.js";
 export { formatDateWithTZOffset, convertToLocalTime, toISOWithOffset } from "./timezone.js";
 export { applyTimezoneOffsetsToFields } from "./time-utils.js";
-export {
-  convertUtcDateTimeToErpLocal,
-  convertErpLocalDateTimeToUtc,
-  getERPTimezone,
-} from "./erp-timezone-utils.js";
 export * from "./time-utils.js";
 
 /**
@@ -69,6 +64,12 @@ export type { HTTPClient, HTTPRequestConfig, HTTPResponse } from "./http-client.
 export * from "./mm-labor-ticket-helpers.js";
 export { getErrorType } from './error-utils.js';
 
+/**
+ * Error formatting utilities
+ */
+export { formatError, formatErrorForLogging } from './error-formatter.js';
+export type { FormattedError } from './error-formatter.js';
+
 /**
  * MM Connector Logger utilities
  */

package/src/utils/local-data-store/jobs-shared-data.ts

@@ -72,8 +72,6 @@ export const setInitialLoadComplete = (complete: boolean): void => {
 };
 
 /**
- * @deprecated The cached numeric offset cannot account for DST changes.
- * Prefer using the cached timezone name with Luxon helpers for conversions.
  * Gets the company's cached current timezone offset (e.g., -5)
  * @returns The cached timezone offset or 0 if not found
  */

package/src/utils/mm-labor-ticket-helpers.ts

@@ -1,13 +1,15 @@
+import { convertToLocalTime, toISOWithOffset } from "./timezone.js";
 import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types.js";
-import { convertUtcDateTimeToErpLocal, getERPTimezone } from "./erp-timezone-utils.js";
 
 /**
- * Converts key datetime fields from UTC (MachineMetrics API) to the ERP's local timezone.
- * All inputs/outputs are ISO-8601 strings, and invalid inputs throw errors.
+ * Apply timezone offsets to datetime fields specifically for the MMApiReceiveLaborTicket object from the Zulu-based MM API
+ * (presumably) before sending to the ERP
  * @param laborTicket The MMApiReceiveLaborTicket object to convert
+ * @param timezoneOffset The timezone offset to apply
  */
 export function convertLaborTicketToLocalTimezone(
-  laborTicket: MMReceiveLaborTicket
+  laborTicket: MMReceiveLaborTicket,
+  timezoneOffset: number
 ): MMReceiveLaborTicket {
   const timeFields = [
     "clockIn",
@@ -18,14 +20,9 @@ export function convertLaborTicketToLocalTimezone(
     "workOrderOperationClosedDate",
   ] as const;
 
-  const timezone = getERPTimezone();
   timeFields.forEach((field) => {
-    const value = laborTicket[field];
-    if (value) {
-      laborTicket[field] = convertUtcDateTimeToErpLocal(value, timezone);
-    } else {
-      laborTicket[field] = null;
-    }
+    const localTime = convertToLocalTime(laborTicket[field], timezoneOffset);
+    laborTicket[field] = localTime ? toISOWithOffset(localTime, timezoneOffset) : null;
   });
   return laborTicket;
 }

package/src/utils/standard-process-drivers/labor-ticket-erp-synchronizer.ts

@@ -2,16 +2,13 @@ import { IERPLaborTicketHandler } from "../../types/erp-connector.js";
 import { MMApiClient } from "../../services/mm-api-service/mm-api-service.js";
 import { MMReceiveLaborTicket } from "../../services/mm-api-service/types/receive-types.js";
 import { convertLaborTicketToLocalTimezone } from "../mm-labor-ticket-helpers.js";
+import { getCachedTimezoneOffset } from "../local-data-store/jobs-shared-data.js";
 import logger from "../../services/reporting-service/logger.js";
 
 /**
  * Handles synchronization of labor tickets between MachineMetrics and ERP systems
  */
 export class LaborTicketERPSynchronizer {
-  // Small allowance to mitigate tiny clock offsets / timestamp granularity differences
-  // between the connector host and MM's timestamps.
-  private static readonly CHECKPOINT_SKEW_MS = 2_000;
-
   /**
    * Synchronizes updated labor tickets from MachineMetrics to an ERP system
    */
@@ -21,9 +18,9 @@ export class LaborTicketERPSynchronizer {
   ): Promise<void> {
     try {
       const mmApiClient = new MMApiClient();
-      const failedLaborTicketRefs = new Set<string>();
-      const attemptedSignatures = new Set<string>();
+      const failedLaborTicketRefs: string[] = [];
 
+      // Initialize and fetch checkpoint (quick operations, don't need prolonged lock)
       await mmApiClient.initializeCheckpoint({
         system: connectorType,
         table: "labor_tickets",
@@ -33,168 +30,95 @@ export class LaborTicketERPSynchronizer {
         },
       });
 
-      /**
-       * We cannot safely checkpoint to "now" without draining, because updates can arrive mid-run.
-       * And we cannot checkpoint to "most recent updatedAt from the initial fetch" because we
-       * update MM (setting laborTicketId on creates), which bumps updatedAt and causes the same
-       * ticket to be re-pulled next cycle.
-       *
-       * We also cannot dedupe only by laborTicketRef, because the same ticket can legitimately
-       * change multiple times within a single run (parts counts, times, reasons, state, etc.).
-       * And we cannot dedupe by (laborTicketRef, updatedAt) because updatedAt is exactly what our
-       * own MM write-back (setting laborTicketId) mutates, creating a false "new version".
-       *
-       * Remedy: drain the window up to a moving barrier time (local "now"), re-fetching until MM
-       * reports no additional unattempted tickets in that window, and dedupe within the run by a
-       * stable business signature (operational fields only; excludes metadata like updatedAt and
-       * excludes SDK-mutated fields like laborTicketId). Then checkpoint to a value that is not
-       * meaningfully ahead of MM's own timestamps (small skew clamp).
-       */
-      const maxPasses = 10;
-      let pass = 0;
-      let barrierTime = new Date().toISOString();
-      let maxMmTimestampWithinBarrier: string | null = null;
-
-      while (pass < maxPasses) {
-        pass += 1;
-        barrierTime = new Date().toISOString();
-
-        const laborTicketsUpdates = await mmApiClient.fetchLaborTicketUpdates({
-          system: connectorType,
-          checkpointType: "export",
-        });
-
-        if (laborTicketsUpdates.length === 0) {
-          if (pass === 1) {
-            logger.info("syncLaborTicketsToERP:No updated labor tickets found");
-          }
-          break;
-        }
+      const fallbackTimestamp = new Date().toISOString();
+      const laborTicketsUpdates = await mmApiClient.fetchLaborTicketUpdates({
+        system: connectorType,
+        checkpointType: "export",
+      });
 
-        // Track the latest MM timestamp we see that is <= the current barrier.
-        for (const ticket of laborTicketsUpdates) {
-          const ts = this.getComparableTicketTimestamp(ticket);
-          if (!ts) continue;
-          if (new Date(ts) > new Date(barrierTime)) continue;
-          if (
-            !maxMmTimestampWithinBarrier ||
-            new Date(ts) > new Date(maxMmTimestampWithinBarrier)
-          ) {
-            maxMmTimestampWithinBarrier = ts;
-          }
-        }
+      if (laborTicketsUpdates.length === 0) {
+        logger.info("syncLaborTicketsToERP:No updated labor tickets found");
+        return;
+      }
 
-        if (pass === 1) {
-          logger.info(
-            `ToERP: Found ${laborTicketsUpdates.length} Labor Ticket Ids and Refs to process`,
-            {
-              laborTickets: laborTicketsUpdates.map(
-                (ticket: MMReceiveLaborTicket) => ({
-                  ref: ticket.laborTicketRef,
-                  id: ticket.laborTicketId,
-                })
-              ),
-            }
-          );
+      logger.info(
+        `ToERP: Found ${laborTicketsUpdates.length} Labor Ticket Ids and Refs to process`,
+        {
+          laborTickets: laborTicketsUpdates.map(
+            (ticket: MMReceiveLaborTicket) => ({
+              ref: ticket.laborTicketRef,
+              id: ticket.laborTicketId,
+            })
+          ),
         }
+      );
 
-        // Build a unique pending list by a stable "business signature", and only consider tickets
-        // whose timestamps are <= the barrierTime (prevents checkpoint gaps if clocks differ).
-        const pending: Array<{ sig: string; ticket: MMReceiveLaborTicket }> = [];
-        const dedupeWithinFetch = new Set<string>();
+      // Find the most recent updatedAt timestamp from labor tickets. This will be used to update
+      // the checkpoint to ensure there is no gap of time for the next sync.
+      const mostRecentUpdate = laborTicketsUpdates.reduce(
+        (latest: string | null, ticket: MMReceiveLaborTicket) => {
+          if (!latest || !ticket.updatedAt) return latest;
+          return new Date(ticket.updatedAt) > new Date(latest)
+            ? ticket.updatedAt
+            : latest;
+        },
+        null as string | null
+      );
 
-        for (const ticket of laborTicketsUpdates) {
-          if (!ticket.laborTicketRef) {
+      await Promise.all(
+        laborTicketsUpdates.map(async (laborTicket: MMReceiveLaborTicket) => {
+          if (!laborTicket.laborTicketRef) {
             logger.error(
               "syncLaborTicketsToERP: laborTicketRef is not set for laborTicket pulled from MM:",
-              { laborTicket: ticket }
+              { laborTicket }
             );
-            continue;
+            return undefined;
           }
 
-          const ts = this.getComparableTicketTimestamp(ticket);
-          if (ts && new Date(ts) > new Date(barrierTime)) {
-            // Defer "future" tickets (relative to local wall clock) to a later run/pass.
-            continue;
+          try {
+            return await this.processLaborTicket(
+              connector,
+              mmApiClient,
+              laborTicket
+            );
+          } catch (error) {
+            failedLaborTicketRefs.push(laborTicket.laborTicketRef);
+            logger.error(
+              `syncLaborTicketsToERP: Error processing laborTicketRef ${laborTicket.laborTicketRef}:`,
+              { error }
+            );
+            return undefined;
           }
-
-          const sig = this.laborTicketBusinessSignature(ticket);
-          if (attemptedSignatures.has(sig) || dedupeWithinFetch.has(sig)) continue;
-          dedupeWithinFetch.add(sig);
-          pending.push({ sig, ticket });
-        }
-
-        if (pending.length === 0) {
-          // Nothing new to do in this barrier window; safe to checkpoint and exit.
-          break;
-        }
-
-        logger.info(
-          `syncLaborTicketsToERP: pass=${pass}/${maxPasses}, barrier=${barrierTime}, pending=${pending.length}`
-        );
-
-        await Promise.all(
-          pending.map(async ({ sig, ticket }) => {
-            // Mark attempted up-front so we don't re-attempt within this run even if MM reorders.
-            attemptedSignatures.add(sig);
-
-            try {
-              return await this.processLaborTicket(connector, mmApiClient, ticket);
-            } catch (error) {
-              failedLaborTicketRefs.add(ticket.laborTicketRef);
-              logger.error(
-                `syncLaborTicketsToERP: Error processing laborTicketRef ${ticket.laborTicketRef}:`,
-                { error }
-              );
-              return undefined;
-            }
-          })
-        );
-      }
-
-      if (pass >= maxPasses) {
-        logger.warn(
-          `syncLaborTicketsToERP: Reached max passes (${maxPasses}). Checkpointing anyway to avoid infinite loops.`
-        );
-      }
+        })
+      );
 
       logger.info(
-        `syncLaborTicketsToERP: ${failedLaborTicketRefs.size} failed labor ticket ids`
+        `syncLaborTicketsToERP: ${failedLaborTicketRefs.length} failed labor ticket ids`
       );
-      if (failedLaborTicketRefs.size > 0) {
-        const failedTicketRefs = Array.from(failedLaborTicketRefs);
+      if (failedLaborTicketRefs.length > 0) {
         logger.info(
-          `syncLaborTicketsToERP: Reporting ${failedTicketRefs.length} labor ticket failures:`,
+          `syncLaborTicketsToERP: Reporting ${failedLaborTicketRefs.length} labor ticket failures:`,
           {
-            failedLaborTicketRefs: failedTicketRefs,
+            failedLaborTicketRefs,
           }
         );
         const addFailedResult = await mmApiClient.addFailedLaborTicketRefs(
           connectorType,
-          failedTicketRefs
+          failedLaborTicketRefs
         );
         logger.info("syncLaborTicketsToERP: addFailedResult:", {
           addFailedResult,
         });
       }
 
-      const checkpointTimestamp = this.computeCheckpointTimestamp({
-        barrierTime,
-        maxMmTimestampWithinBarrier,
-        skewMs: this.CHECKPOINT_SKEW_MS,
-      });
-
-      await mmApiClient.saveCheckpoint({
+      mmApiClient.saveCheckpoint({
         system: connectorType,
         table: "labor_tickets",
         checkpointType: "export",
         checkpointValue: {
-          timestamp: checkpointTimestamp,
+          timestamp: mostRecentUpdate || fallbackTimestamp,
         },
       });
-      logger.info("syncLaborTicketsToERP: Checkpoint saved:", {
-        checkpointTimestamp,
-      });
     } catch (error) {
       logger.error("syncLaborTicketsToERP: Error:", error);
     }
@@ -291,10 +215,10 @@ export class LaborTicketERPSynchronizer {
   ): Promise<MMReceiveLaborTicket> {
     let laborTicketResult: MMReceiveLaborTicket;
 
-    // Convert MM's UTC timestamps into the ERP's local timezone before invoking connector code.
-    // Connector implementations should treat the incoming values as localized wall time and avoid
-    // applying any further timezone shifts.
-    laborTicketResult = convertLaborTicketToLocalTimezone(laborTicket);
+    laborTicketResult = convertLaborTicketToLocalTimezone(
+      laborTicket,
+      getCachedTimezoneOffset()
+    );
 
     logger.info(
       `processing laborTicket, id=${laborTicket.laborTicketId}, ref=${laborTicket.laborTicketRef}`
@@ -334,84 +258,4 @@ export class LaborTicketERPSynchronizer {
 
     return laborTicketResult;
   }
-
-  /**
-   * A stable identity for "did the business-relevant contents of this labor ticket change?"
-   *
-   * IMPORTANT: Excludes fields that the SDK itself mutates (e.g. laborTicketId, updatedAt),
-   * otherwise we'd reprocess the write-back bump on the next cycle.
-   */
-  private static laborTicketBusinessSignature(ticket: MMReceiveLaborTicket): string {
-    const reasons = (ticket.reasons ?? [])
-      .map((r) => {
-        const reason: any = (r as any)?.reason ?? {};
-        return (
-          reason.reasonId ??
-          reason.code ??
-          reason.reasonRef ??
-          reason.rejectReasonRef ??
-          ""
-        );
-      })
-      .filter((v) => v !== "" && v !== null && v !== undefined)
-      .map(String)
-      .sort();
-
-    const signatureObject = {
-      laborTicketRef: ticket.laborTicketRef ?? null,
-      clockIn: ticket.clockIn ?? null,
-      clockOut: ticket.clockOut ?? null,
-      goodParts: ticket.goodParts ?? null,
-      badParts: ticket.badParts ?? null,
-      state: ticket.state ?? null,
-      type: ticket.type ?? null,
-      transactionDate: ticket.transactionDate ?? null,
-      workOrderId: ticket.workOrderId ?? null,
-      sequenceNumber: ticket.sequenceNumber ?? null,
-      personId: ticket.personId ?? null,
-      resourceId: ticket.resourceId ?? null,
-      lot: ticket.lot ?? null,
-      split: ticket.split ?? null,
-      sub: ticket.sub ?? null,
-      comment: ticket.comment ?? null,
-      workOrderOperationClosedDate: ticket.workOrderOperationClosedDate ?? null,
-      reasons,
-    };
-
-    return JSON.stringify(signatureObject);
-  }
-
-  /**
-   * Selects a comparable timestamp for windowing decisions.
-   * Prefer updatedAt; fall back to other stable timestamps if needed.
-   */
-  private static getComparableTicketTimestamp(
-    ticket: MMReceiveLaborTicket
-  ): string | null {
-    return (
-      ticket.updatedAt ??
-      ticket.createdAt ??
-      ticket.transactionDate ??
-      ticket.clockOut ??
-      ticket.clockIn ??
-      null
-    );
-  }
-
-  private static addMsToIso(iso: string, ms: number): string {
-    return new Date(new Date(iso).getTime() + ms).toISOString();
-  }
-
-  private static computeCheckpointTimestamp(options: {
-    barrierTime: string;
-    maxMmTimestampWithinBarrier: string | null;
-    skewMs: number;
-  }): string {
-    const { barrierTime, maxMmTimestampWithinBarrier, skewMs } = options;
-
-    if (!maxMmTimestampWithinBarrier) return barrierTime;
-
-    const mmPlusSkew = this.addMsToIso(maxMmTimestampWithinBarrier, skewMs);
-    return new Date(mmPlusSkew) < new Date(barrierTime) ? mmPlusSkew : barrierTime;
-  }
 }

package/src/utils/standard-process-drivers/mm-entity-processor.ts

@@ -29,13 +29,7 @@ import { ErrorProcessor } from "./error-processor.js";
  */
 export class MMEntityProcessor {
   /**
-   * Writes entities to MM API with deduplication and caching.
-   *
-   * IMPORTANT: All datetime fields on `mmRecords` MUST already be expressed as
-   * ISO-8601 UTC strings (either trailing `Z` or an explicit offset). The SDK
-   * does not apply timezone conversion on this path. It forwards values directly
-   * to MachineMetrics and only reserializes them for validation. Connector code
-   * is responsible for converting local ERP times to UTC before invoking this API.
+   * Writes entities to MM API with deduplication and caching
    */
   static async writeEntities(
     entityType: ERPObjType,