The ERPNext connector
How the connector reads ERPNext over the Frappe REST API: the role, custom fields and webhooks the setup script creates, the connection settings, what is published for items, batches, serial numbers and parties, the default mapping, EPCIS events from stock documents, and the write-back into ERPNext.
ERPNext holds the items a company sells, the batches and serial numbers it tracks, the suppliers and customers it trades with, and the stock documents that move goods between them. The connector reads all of this through the Frappe REST API, publishes items, batches, serial numbers and parties to the OpenEPCIS catalog under their GS1 keys, and can report the delivery notes, purchase receipts and stock entries as EPCIS events. A scan of the product's GS1 Digital Link then reaches the master data, the passport derived from it and the events about the item.
No Frappe app is installed. What ERPNext has to contribute (a role, a few custom fields, one custom DocType, the webhooks and a panel on the Item form) is created through the same REST API by a setup script that comes with the connector. Everything on this page was measured against ERPNext v16.33.0. The general mechanics of polling, mapping and publishing are explained in how a connector works.
Preparing ERPNext
The setup script
The script needs Python 3.8 or newer and the API key pair of a System Manager for the run itself. It is told where ERPNext lives, under which public address it reaches the connector, and which connection name the webhooks should carry:
export ERPNEXT_API_KEY=<key of a System Manager>
export ERPNEXT_API_SECRET=<secret of a System Manager>
export OPENEPCIS_WEBHOOK_SECRET=<secret shared with the connector>
openepcis-erpnext-setup.py --url https://erp.example.test --connector-base-url https://connectors.example.test --connection erp1 plan
plan is the default and only reads the site, printing what would change. apply makes those changes, and verify exits with status 1 if anything still differs. The script compares field by field, writes only the differences, and never deletes a document, a child row or a permission, so a second apply reports everything as unchanged. Adding --create-api-user openepcis-connector@your-domain also creates the connector's API user with the role "OpenEPCIS Connector" and nothing else, and prints its key and secret once. Store them right away, because a later run leaves an existing user and its keys alone. A new secret is issued with Generate Keys in the user form.
Where the script cannot run, the same steps can be done by hand in the order the script performs them. The section on what the script creates below lists everything it touches.
The API user and its role
The connector authenticates with an API key pair, sent as Authorization: token key:secret. A dedicated user is worth the small effort over a personal account: the keys survive their owner leaving the company, and the audit log names the connector.
The role "OpenEPCIS Connector" can read Item, Supplier, Customer, Batch, Serial No, Warehouse, Company, UOM, Delivery Note, Purchase Receipt, Stock Entry, Serial and Batch Bundle, Webhook and System Settings. It can create and write the custom DocType OpenEPCIS Link, and it cannot delete anything or write to any standard DocType. Read access to System Settings matters more than it looks: without it the connector cannot see the system time zone, and event times computed from posting_date and posting_time would be off by the UTC offset.
The script grants these rights through the permission manager, which first copies a DocType's standard permissions into Custom DocPerm. Anyone setting this up by hand should do the same in Role Permissions Manager, adding a rule at level 0 with only Read ticked. A Custom DocPerm inserted directly would become the only rule on that DocType, and every standard role would lose its access.
Custom fields for the GS1 keys
Stock ERPNext has no place for GS1 identifiers, so three custom fields are added:
custom_glnon Company, Warehouse, Supplier and Customer holds the 13-digit Global Location Number. On Supplier and Customer it is also the key under which the party is held in the catalog, and a party without a GLN is skipped during sync and named in the log.custom_gpc_codeon Item holds the eight-digit GS1 GPC brick.custom_unece_codeon UOM holds the UN/ECE Recommendation 20 code of the unit, such asH87for pieces,KGMorLTR. Event quantities of batches carry it as their unit.
The GTIN needs no custom field, because it already lives in the item's barcode table under Item → Barcodes. The connector takes the first row whose barcode type belongs to the GS1 family (EAN, EAN-13, EAN-8, UPC, UPC-A, GTIN, GTIN-14, GS1, JAN) and whose value passes the GS1 check digit. A mistyped row therefore never hides a correct one further down. An item with a barcode 9521234000013 of type EAN is published under /01/09521234000013; an item without any valid GS1 barcode is skipped and named in the log. Why the GTIN has to come from a field of its own, and how it relates to the item code, is explained in identifiers: GTIN and SKU.
Batches and serial numbers
If an item has Has Batch No or Has Serial No switched on, the connector also publishes the instance level. A batch becomes the document under /01/<gtin>/10/<batch> and a serial number the document under /01/<gtin>/21/<serial number>, both under the GTIN from the item's barcode table. Batches and serial numbers of items without the respective tracking are stock accounting and stay out of the catalog. ERPNext v16 refuses to submit any document with batch or serial rows until Stock Settings → Activate Serial and Batch No for Item is on, so this switch belongs to the preparation.
Webhooks
The script creates eleven webhooks, all pointing at https://<connectors-host>/webhooks/erpnext/<connection>. Item, Supplier, Customer, Batch and Serial No are hooked on_update, which also covers creation. Delivery Note, Purchase Receipt and Stock Entry are hooked both on_submit and on_cancel. Each webhook sends the JSON body {"doctype", "name", "docstatus"} and is signed: Frappe computes an HMAC-SHA256 over the body with the webhook secret and sends it base64-encoded in X-Frappe-Webhook-Signature. The connector checks it against the connection's source.webhook-secret and answers anything that does not match with 401.
What the script creates
For reference, these are the definitions the script applies, in its order: the role "OpenEPCIS Connector" with desk access; the custom fields above (custom_gln as Data of length 13, custom_gpc_code of length 8, custom_unece_code of length 3); the DocType "OpenEPCIS Link" in module Stock, named by its field reference_key; the read permissions of the role; the webhooks, each with request structure JSON, a Content-Type: application/json header and Enable Security with the webhook secret; a Client Script on the Item form; and optionally the API user. A permission row on a new DocType starts with write, create, delete, report, export, share, print and email all switched on, so anyone creating OpenEPCIS Link by hand has to switch off every right a role should not have.
The connection
A connection names one ERPNext and one catalog:
openepcis.connectors.connections.erp1.source.type=erpnext
openepcis.connectors.connections.erp1.source.url=https://erp.example.test
openepcis.connectors.connections.erp1.source.auth.kind=api-key-secret
openepcis.connectors.connections.erp1.source.auth.key=<API key of the connector user>
openepcis.connectors.connections.erp1.source.auth.secret=<API secret of the connector user>
openepcis.connectors.connections.erp1.source.webhook-secret=<shared webhook secret>
openepcis.connectors.connections.erp1.source.webhook-base-url=https://connectors.example.test
openepcis.connectors.connections.erp1.source.options.locale=en
openepcis.connectors.connections.erp1.target.resolver-url=https://id.example.test
openepcis.connectors.connections.erp1.target.gcp-prefixes=9521234
openepcis.connectors.connections.erp1.target.offline-token=<platform offline token>
openepcis.connectors.connections.erp1.target.economic-operator-gln=9521234000006
openepcis.connectors.connections.erp1.dry-run=true
source.url is the site's origin, since the connector adds the Frappe API paths itself. ERPNext stores one language per text field and hands over a bare string, while the catalog files names and descriptions under a language key and rejects a blank one, so source.options.locale is required and states which language the texts are written in. source.webhook-base-url is the public address under which ERPNext reaches the connector; it is only needed for the webhook check in the diagnosis ladder, described below. target.economic-operator-gln sets that GLN as the manufacturer on every product whose source names none, which the EN 18223 passport requires.
The API secret, the webhook secret and the offline token belong in a Kubernetes secret; the block above only names the keys. How the offline token is issued, and what revoking it does to a running connection, is covered in Integration Tokens.
What gets published
Each Item with a valid GS1 barcode becomes a product document at /01/<gtin>. Each Batch of a batch-tracked item becomes a document at /01/<gtin>/10/<batch>, and each Serial No of a serial-tracked item one at /01/<gtin>/21/<serial>. The catalog validates instance documents against the full product schema, so the class-level fields (product name, brand) travel along from the item. For batches and serial numbers the connector also registers the linkset entry that resolves ?linkType=masterData to the instance document.
Supplier and Customer records with a GLN become organisation documents under that GLN. A party in ERPNext carries no field for what kind of party it is, so the adapter derives it from the DocType: both are published with the GLN type LEGAL_ENTITY, a supplier with the role SUPPLIER and a customer with the role BUYER. These two values pass through the mapping, so a deployment where a wholesaler is a distributor, or where a GLN identifies a plant, can change them in its own mapping file.
The default mapping
The default mapping is small and carries only what every ERPNext installation holds, plus the custom fields the setup creates. Every rule runs from ERPNext to the catalog, and nothing in the catalog is ever written back into ERPNext's own fields.
For items, item_name becomes productName and description becomes productMarketingMessage, the GS1 term for consumer-friendly prose. productDescription stays unmapped because the vocabulary defines it as an identifying line built from brand and descriptors, and ERPNext has no field that holds one. brand becomes brand.brandName, and custom_gpc_code becomes gpcCategoryCode.
Batches and serial numbers repeat the four item rules, read through item.*. A batch adds its manufacturing_date as productionDate and its expiry_date as bestBeforeDate. The batch quantity is left out, because its unit is the stock unit of each item and varies from item to item, which a mapping rule with one fixed unit cannot express. A serial number adds its batch_no as hasBatchLotNumber. The identity of an individual item is GTIN plus serial number, and the batch is an attribute of it. The catalog accepts that attribute only once its resolver has switched on the rule openepcis.granularity.canonical-serial, which the connector cannot see, so the connection states it with source.options.serial-lot-attribute=true. Without that option the batch is removed from serial-number documents, with one notice per connection in the log.
For parties, supplier_name or customer_name becomes organizationName, custom_gln becomes globalLocationNumber, and the derived values described above become glnType and organizationRole. A website is left out because the catalog's organisation document has no field for one.
Further fields such as weights, country of origin or additional descriptions go into a copy of the default mapping, entered as the connection's mapping-file. A rule consists of a source path, a target term and optionally a value kind such as localized or a fixed unit. The format is described under the mapping format.
How sync works
The connector polls ERPNext on the connection's interval, every 15 minutes unless poll-interval says otherwise. It lists each DocType ordered by modified and continues from the last timestamp it consumed, then fetches every hit in full. Records whose payload hash matches the last publication produce no write. A full run at night reconciles whatever a poll or a webhook missed, and can be switched off per connection with full-sync-enabled=false.
The webhooks make changes arrive sooner. A webhook only names a record: after it arrives, the connector reads that record fresh through the API and drops the payload. Master data then goes into the delta sync, and the three stock documents go to a targeted event capture. The poll stays necessary in one measured case: serial numbers created by a purchase receipt or a manufacture are inserted in bulk and fire no webhook, and the next poll picks them up.
Before the first run, the diagnosis ladder shows what already works:
curl https://<connectors-host>/connections/erp1/diagnostics
For ERPNext it reads the webhook registry and names every DocType that has no enabled webhook pointing at the connector, and every stock DocType hooked on_submit without on_cancel.
EPCIS events
The connector can report events to the platform's EPCIS repository. On the first publish of a batch or serial number it captures an ObjectEvent with bizStep commissioning. Submitted Delivery Notes, Purchase Receipts and Stock Entries become shipping and receiving ObjectEvents, TransformationEvents for manufacture and repack, and a storing event for a material transfer between two GLNs. Serial numbers become SGTINs, and batches become LGTINs with a quantity, both read from the Serial and Batch Bundle of each document row. The event time is posting_date plus posting_time in the system time zone.
The location of an event is the GLN of the warehouse, then of its parent warehouses, then of the company. A document whose location has no GLN anywhere produces no event, and the log says why. Partner GLNs appear in the source and destination lists of shipping and receiving events. A cancelled document is reported again under the same event ID with an error declaration.
Both kinds of events are switched on per connection:
openepcis.connectors.connections.erp1.epcis.enabled=true
openepcis.connectors.connections.erp1.epcis.url=https://api.example.test
openepcis.connectors.connections.erp1.epcis.events.enabled=true
epcis.events.streams limits capture to some of the three document types, and epcis.read-point-gln and epcis.biz-location-gln set read point and business location for the commissioning events. The business step and disposition of each kind of document can be overridden with source.options.events.<kind>.biz-step and source.options.events.<kind>.disposition, where the kind is one of delivery-note, delivery-note-return, purchase-receipt, purchase-receipt-return, manufacture, repack or material-transfer. The platform user behind the connection also needs the realm role <tenant>/capture, which the diagnosis ladder checks as a step of its own. How events relate to the catalog is explained in events, credentials and representations.
Write-back and the Item panel
The connector can record what it knows about an ERPNext record in the custom DocType OpenEPCIS Link. Each row is named after its reference_key, such as Item::SKU-1, and holds the GS1 key, the Digital Link, the verdict status (OK, ACTION_REQUIRED or UNVERIFIED) with its reason, the GCP ownership, the licensee and the event IDs. The Digital Link uses the domain of the tenant's resolver, where the linksets actually resolve. The connector writes only into this DocType, so its API user stays read-only on Item. Stock User, Sales User and Item Manager can read the rows. Write-back is switched on per connection:
openepcis.connectors.connections.erp1.source.options.write-back=true
The Client Script installed by the setup reads that row and shows it in the Connections tab of the Item form, in a section headed "OpenEPCIS": the Digital Link with a copy button, the verdict as a coloured badge and a QR code of the Digital Link. An item without a GS1 barcode gets a hint in its place. The panel only reads, so opening or saving an item starts nothing in the connector.
Going live
A new connection starts with dry-run=true, which is the default, and only logs what it would write. Events are never captured in a dry run, since they are append-only and cannot be taken back. Read that log carefully, because real registrars sit behind the catalog, GS1 production among them, and arming the connection takes the single line dry-run=false. Test data in a connected ERPNext should carry keys from the GS1 test range only, GTINs and GLNs starting with 952, until the connection is meant to publish real products.
dry-run is on by default: a connection publishes nothing and captures no events until you set dry-run=false for it.