Referensi sinkronisasi native OpexMX dengan Epicor Kinetic (work order, aset, suku cadang, purchase order), dan peran OpexFlow untuk konfirmasi pengiriman posting kembali ke ERP.

Lokasi: Management → API & Integrations (grup Admin) → Epicor. Setiap integrasi memiliki tab Overview, Connection, Endpoints & Payloads, Field Mapping, Sync History, dan Failed Records.

Ada dua cara OpexMX bekerja dengan Epicor Kinetic, dan keduanya punya tugas yang berbeda.

Sinkronisasi native. Engine sinkronisasi bawaan yang membaca dan menulis business object Epicor lewat REST API Kinetic, sesuai jadwal, untuk empat jenis data.
OpexFlow untuk posting. Untuk transaksi yang harus sampai ke ERP dengan bukti pengiriman, OpexMX mengirim webhook bertanda tangan ke OpexFlow. OpexFlow mengirimkannya, mengonfirmasinya, dan menandai apa yang tidak sampai.

Halaman ini menjelaskan sinkronisasi native berdasarkan kode produk, lalu jalur OpexFlow.

Status halaman ini

Sinkronisasi native dijelaskan sebagai kemampuan produk, berdasarkan kode server OpexMX. Halaman ini tidak melaporkan hasil uji untuk sinkronisasi native, dan tidak ada hasil uji yang diklaim di sini.

Uji terekam ada untuk jalur OpexFlow. Hasilnya dipublikasikan sebagai studi kasus OpexFlow, ditautkan di bagian akhir. Setiap studi menyebutkan apa yang disimulasikan dan apa yang nyata.

Sinkronisasi native

Apa yang disinkronkan

Data OpexMX	Business object dan kunci Epicor
Tiket pemeliharaan (work order)	`Erp.BO.JobEntrySvc` / `JobEntries`, kunci `JobNum`
Aset	`Erp.BO.EquipSvc` / `Equips`, kunci `EquipID` (dengan `Plant`)
Suku cadang	`Erp.BO.PartSvc` / `Parts`, kunci `PartNum`
Purchase order, beserta baris	`Erp.BO.POSvc` / `POes`, kunci `PONum` (numerik), baris diperluas dari `PODetails`

Keempatnya dapat dikonfigurasi sebagai inbound (Epicor ke OpexMX), outbound (OpexMX ke Epicor), atau bidirectional. Arah ditetapkan per entitas dalam konfigurasi integrasi. Hanya entitas yang tercantum dalam konfigurasi yang disinkronkan. Objek Epicor lain tidak dibaca atau ditulis.

Nama entity set dan kunci dalam kode diberi catatan telah dicek terhadap $metadata Kinetic REST v2 dari EPIC06, company demo milik Epicor. Itu pemeriksaan skema, bukan uji sinkronisasi.

Pemetaan field default

Setiap entitas membawa pemetaan default dari field Epicor ke field OpexMX. Override per entitas dapat ditambahkan dalam konfigurasi integrasi, dan tab Field Mapping menampilkan nilai defaultnya.

Entitas	Field Epicor	Field OpexMX
Work order	`JobNum`	`externalId`
	`PartDescription`	`title`
	`CommentText`	`description`
	`StartDate` / `DueDate`	`scheduledStartDate` / `scheduledEndDate`
Aset	`EquipID`	`code`
	`Description`	`name`
	`TypeID`	`assetType`
	`OEM`, `Model`, `SerialNum`	`manufacturer`, `model`, `serialNumber`
	`Plant`	`location`
Suku cadang	`PartNum`	`code`
	`PartDescription`	`name`
	`IUM`	`unit`
	`ProdCode`	`category`
Purchase order	`PONum`	`externalId`
	`VendorNum`	`supplierCode`
	`VendorName`	`supplierName`
	`OrderDate`	`orderDate`

Beberapa nilai diturunkan, bukan disalin:

Status work order berasal dari flag job Epicor: closed, lalu complete, lalu released (in_progress), dan job yang belum released berstatus open. Ke arah sebaliknya, status OpexMX mengatur flag yang sama. Job bertipe MNT menjadi tiket preventif, tipe job lain menjadi tiket korektif.
Status aset berasal dari InActive: aktif atau tidak aktif.
Status purchase order berasal dari OpenOrder: issued bila terbuka, closed bila tidak. Ke arah keluar, status closed atau received menghapus OpenOrder.
Baris purchase order memetakan POLine, PartNum, LineDesc, OrderQty, IUM, dan DocUnitCost ke nomor baris, kode suku cadang, deskripsi, kuantitas, satuan, dan harga satuan.

Cara data dicocokkan

Data masuk dicocokkan dengan data OpexMX yang ada berdasarkan kunci Epicor, lalu diperbarui, atau dibuat bila tidak ada yang cocok:

Entitas	Dicocokkan pada
Work order	`externalId` (nomor job)
Aset	`code` (ID equipment)
Suku cadang	`code` (nomor part)
Purchase order	Nomor PO

Ke arah keluar, engine mencari data di Epicor berdasarkan kuncinya dengan $filter. Bila ada, engine mengirim PATCH ke URL entitas berkunci (company dan field kunci ada di alamat). Bila tidak ada, atau bila pencarian itu sendiri gagal setelah dua percobaan, engine mengirim POST untuk membuatnya. Payload berupa JSON entitas polos untuk Kinetic REST v2.

Koneksi dan autentikasi

Koneksi disimpan bersama integrasi dan berisi:

base URL application server Epicor, nama instance, dan ID company, yang juga muncul di path request
versi REST API, v2 atau v3, dengan v3 dipakai bila tidak diatur
API key, dikirim sebagai header x-api-key, wajib untuk v2 ke atas
tipe autentikasi: basic (username dan password) atau bearer (token)
timeout request, default 30 detik
kebijakan retry opsional (lihat Retry di bawah)

Request dikirim ke /api/{version}/odata/{company}/Erp.BO.{service}/{entity}, lewat OData v4.

Kredensial dienkripsi saat disimpan. Tab Connection hanya menampilkan host, company, versi API, serta apakah API key dan kredensial sudah diatur. Rahasia tidak pernah dikirim ke browser. Garis miring di akhir atau spasi tersasar pada base URL dibersihkan sebelum dipakai.

Test connection meminta satu part ($top=1) dengan timeout 10 detik. Hasilnya berhasil atau gagal beserta latensi. Respons 401 dilaporkan sebagai kegagalan autentikasi, bukan sebagai sistem yang terjangkau. Teks error Epicor sendiri, misalnya pesan API key tidak valid, diteruskan agar penyebabnya terlihat di layar.

Jadwal

Satu tick scheduler berjalan setiap 15 menit dan memeriksa setiap integrasi yang aktif.
Integrasi dianggap jatuh tempo bila belum pernah sinkron, atau bila waktu sejak sinkron terakhir minimal sebesar pengaturan scheduleMinutes-nya. Defaultnya 15 menit. Karena tick-nya 15 menit, pengaturan yang lebih pendek tetap berjalan paling banyak sekali per tick.
Di Cloudflare, setiap integrasi memiliki Durable Object sendiri. Ia menyinkronkan per potongan melalui alarm tick sehingga proses panjang tahan terhadap eviction dan batas waktu. Instalasi on-premise menjalankan sinkronisasi yang sama secara inline di proses server.
Probe kesehatan terpisah berjalan setiap 30 menit dan memanggil uji koneksi untuk setiap integrasi aktif, sehingga koneksi yang rusak terlihat di antara sinkronisasi.
Pengguna juga dapat memulai sinkronisasi manual, mengulang satu entitas, atau menguji koneksi dari layar integrasi.

Sinkronisasi inkremental dan paging

Data bergerak dalam halaman berisi 25 record. Request masuk memakai $top dan $skip. Arah keluar membaca baris OpexMX yang berubah, 25 sekaligus, diurutkan berdasarkan id.

Setiap kombinasi integrasi, entitas, dan arah memiliki watermark, yaitu waktu pass lengkap terakhir:

Inbound: bila entitas punya delta field (misalnya LastActivityDate), request menambahkan $filter=<field> ge <watermark>. Run pertama belum punya watermark, jadi berupa backfill penuh. Tanpa delta field, seluruh record dibaca setiap kali.
Outbound: baris yang berubah sejak watermark dikirim. Tanpa watermark, engine menengok 24 jam ke belakang.
Watermark maju hanya bila halaman terakhir pass itu pendek, artinya entitas sudah habis. Bila fetch gagal, watermark tidak maju dan run berikutnya mengulang jendela yang sama.

Retry

Panggilan ke Epicor dibungkus retry dengan exponential backoff dan jitter:

default 3 percobaan, mulai 1 detik dengan pengali 2, dibatasi 30 detik per jeda
retry policy koneksi dapat mengubah jumlah percobaan, jeda awal, dan pengali
di-retry: error jaringan, timeout, dan HTTP 408, 425, 429, 500, 502, 503, 504
tidak di-retry: respons 4xx lain, termasuk 401, yang langsung gagal

Dead letter

Record yang tidak bisa dipetakan, disimpan, atau dikirim tidak menghentikan run. Kegagalan disimpan bersama payload record dan teks error di tabel dead letter, dan sinkronisasi lanjut ke record berikutnya.

Setiap kegagalan yang tersimpan diputar ulang otomatis setelah run. Replay menunggu 1 menit, lalu 2, lalu 4, dan seterusnya, hingga 30 menit di antara percobaan.
Setelah 5 percobaan kegagalan ditandai dead dan tidak lagi diputar ulang otomatis.
Kegagalan inbound diputar ulang dari record yang sudah dipetakan. Kegagalan outbound dipetakan dan dikirim lagi.
Fetch halaman yang gagal bukan dead letter. Ia dicatat sebagai error di sync log dan run berikutnya mengulanginya.

Status integrasi adalah error selama ada kegagalan yang pending, retrying, atau dead, dan success bila antrean bersih.

Apa yang dilihat pengguna

Tab	Isi
Overview	Protokol, aktif atau tidak, waktu sinkronisasi terakhir, tipe autentikasi, hasil terbaru per entitas (record diproses, gagal, error pertama) dengan tombol retry per entitas, serta daftar entitas dan arah yang disinkronkan
Connection	Host, company, versi API, timeout, retry policy, dan apakah kredensial serta API key ada
Endpoints & Payloads	Endpoint dan payload request Epicor yang dipakai sinkronisasi, dengan company dan versi terisi
Field Mapping	Pemetaan default untuk setiap entitas
Sync History	Sync log: satu baris per run entitas, dengan waktu mulai dan selesai, arah, jumlah record diproses, berhasil, dan gagal, serta error
Failed Records	Daftar dead letter dengan entitas, kunci record, status, jumlah percobaan, dan error. Putar ulang satu record, ulangi semua kegagalan yang jatuh tempo, atau buang kegagalan

Sync log dan daftar kegagalan adalah tempat untuk memeriksa bila ada record yang hilang.

Batasan

Epicor di-poll. Engine tidak menerima event dari Epicor, dan interval terpendek adalah tick 15 menit.
Empat jenis data tercakup. Objek Epicor lain tidak dibaca atau ditulis.
Engine tidak menangani penghapusan. Ia membuat dan memperbarui record.
Tidak ada penyelesaian konflik tingkat field. Untuk entitas bidirectional, setiap run membaca dari Epicor lalu mengirim baris OpexMX yang berubah.
Pemetaan field berdasarkan nama field. Nilai terhitung dan konversi satuan di luar aturan status di atas bukan bagian dari pemetaan default.
Paging inbound mengirim $top dan $skip dan tidak menambahkan $orderby. Studi Epicor OpexFlow (lihat Bukti) menemukan bahwa paging tanpa urutan terhadap server uji Epicor yang nyata dapat melewatkan baris. Bila ini penting, pastikan perilaku paging pada sistem Epicor tujuan sebelum mengandalkan pembacaan inbound penuh.

Di mana OpexFlow berperan

Sinkronisasi native memindahkan data master dan transaksional sesuai jadwal. Ia tidak dibuat untuk membuktikan bahwa satu posting tertentu sampai, misalnya goods issue terhadap sebuah work order. Untuk itu OpexMX memakai webhook keluar dan OpexFlow.

Apa yang dilakukan pengirim webhook OpexMX

Webhook berlangganan jenis event per tenant, dengan wildcard seperti ticket.*. Jenis event mencakup work_order.completed, part.low_stock, purchase_order.received, asset.status_changed, dan lainnya.
Setiap pengiriman adalah POST dengan body JSON. Body berisi id event yang unik, jenis event, tenant, dan data record.
Setiap request ditandatangani. Header X-Webhook-Signature berisi timestamp dan HMAC-SHA256 dari timestamp dan body, dibuat dengan secret webhook. X-Webhook-Id, X-Webhook-Timestamp, dan X-Webhook-Event juga dikirim. Secret dapat dirotasi.
Timeout 30 detik. Setiap percobaan ditulis ke delivery log dengan status, durasi, dan respons.
Kesehatan webhook dihitung dari 10 pengiriman terakhir: healthy pada keberhasilan 80% atau lebih, degraded pada 50% atau lebih, selain itu failing.
Setelah error jaringan atau timeout pengirim mencoba lagi, default hingga 3 percobaan dengan jeda 60 detik, lalu 120 detik. Respons berstatus tidak sukses dicatat sebagai pengiriman gagal dan tidak dikirim ulang oleh pengirim.

Poin terakhir itu alasan penerima yang menyimpan catatan sendiri tentang apa yang diterimanya dan apa yang dikonfirmasi oleh target menjadi berguna.

Yang ditambahkan OpexFlow

OpexFlow berada di antara webhook OpexMX dan ERP. Untuk posting kembali ke ERP ia menyediakan:

Pemeriksaan tanda tangan. Request yang gagal diperiksa ditolak dan tidak pernah masuk ke flow.
Sekali per event. Id event yang berulang dikenali dan dibuang, sehingga pengiriman ulang tidak memposting dua kali.
Konfirmasi pengiriman. Flow mencatat event di sisi OpexMX dan jawaban ERP di sisi ERP, lalu mengembalikan referensi dokumen ERP ke pengirim.
Retry. Kegagalan sementara ERP dijawab kembali ke pengirim sebagai error yang dapat di-retry, bukan hilang.
Dead letter dengan replay. Penolakan permanen dari ERP disimpan beserta record aslinya. Seseorang dapat memperbaikinya dan memutarnya ulang, dan tindakan itu tercatat atas nama login mereka.
Peringatan. Penolakan juga dapat mengirim email ke mailbox operasi.
Reconcile malam hari. Perbandingan terjadwal kedua sisi berdasarkan id event mengubah setiap selisih menjadi kasus pengecualian dengan status dan penanggung jawab.
Tampilan kesehatan. Jumlah panggilan, error, retry, dan latensi untuk setiap panggilan eksternal.

Belum ada uji terekam yang memasangkan posting OpexMX dengan sistem Epicor yang hidup. Pola posting itu sendiri telah diuji terhadap SAP, dan sisi baca Epicor telah diuji di OpexFlow terhadap respons Epicor yang direkam. Antarmuka Epicor yang dipakai untuk posting (business object REST, pembacaan BAQ) diatur per instalasi.

Bukti

Keduanya adalah studi kasus OpexFlow. Masing-masing memiliki bagian cakupan yang menyebutkan apa yang nyata dan apa yang disimulasikan.

Pola posting, diuji terhadap SAP. OpexMX to SAP: confirmed delivery for every posting. Webhook bertanda tangan, sekali per event, dead letter dengan replay, reconcile malam hari. Dijalankan terhadap middleware SAP simulasi, bukan sistem SAP yang hidup.
Sisi baca Epicor, diuji di OpexFlow. Epicor general ledger to Postgres: one request per partition, checked by count. Flow, pemuatan, retry, dead letter, dan reconcile adalah run lokal yang nyata. Sisi Epicor adalah mock yang memutar ulang respons yang direkam dari EPIC06, company demo milik Epicor. Tidak ada sistem Epicor yang hidup atau sistem pelanggan yang dipanggil.

Studi itu juga melaporkan bahwa paging $top/$skip tanpa urutan terhadap server uji Epicor yang nyata menghilangkan baris (12 dari 17.160 pada satu trial balance), ditemukan dalam probe sebelumnya yang tidak dapat direproduksi mock. Lihat batasan di atas untuk penerapannya pada sinkronisasi native.

OpexMX dengan Epicor Kinetic