SAP Business One connector

A small program that reads your SAP Business One documents and writes them to DawaTrack through the Partner API, with the same rules every partner's calls follow. This page says what it reads, what it writes, what it needs from you, and what it doesn't do yet.

Status

• Built, not yet run against a live SAP system. It is tested against DawaTrack itself and against SAP's published Service Layer documentation. Some field names are confirmed only from SAP's documents; the first company's data confirms them.
• Run by hand for now. A schedule or a background service is set up with each company, to fit where its SAP Business One runs.
• Stock transfers between your warehouses aren't written yet. They wait for the first company's warehouse layout.

It is set up with you, not downloaded. Talk to us to start.

What becomes what

It reads documents changed since its last run, through the Service Layer (OData v3 /b1s/v1 or v4 /b1s/v2), and writes one event per batch, or per serial, of each line.

The rules it follows

Nothing is guessed. A line that can't be written stops, and goes on the run report with what to fix.

• GTIN: the line's barcode, else the item's barcode, else an item field you name (for a GTIN kept in a user-defined field). The GS1 check digit is checked; no GTIN, or a wrong check digit, stops the line.
• Batch: from the line's batch or serial numbers. A line with neither stops: a batch is never chosen for it.
• Quantity: a whole number of units.
• Customers and suppliers: from a mapping you confirm once (below). An unmapped one stops its lines.
• Which receipt a delivery came from: the oldest receipt of the batch that the connector recorded. A delivery drawing on two receipts is two SHIPs, each naming its receipt.
• Running twice writes nothing twice. Each event carries its own idempotency key, built from the document:

Idempotency-Key: sapb1:<company>:<document type>:<DocEntry>:<LineNum>:<batch or serial>

Cancelled documents

Cancelling a delivery or a goods receipt in SAP Business One marks it cancelled and writes a cancellation document beside it. The connector:

• retracts every event it wrote for the cancelled document, a delivery's shipments before the receipts they drew on, and gives the units back to those receipts;
• never writes the cancellation document as a movement;
• retracts nothing twice when it reads the document again.

DawaTrack refuses to retract an event something follows from: a shipment the receiver has already received, say, or a receipt a delivery drew on that wasn't cancelled. The refusal goes on the run report in DawaTrack's words, as SAP refuses to cancel a receipt whose stock was issued.

What we need from you

1. Service Layer access: its address and company database, and a user that can read documents and items. The password stays in the connector's environment, never in a file.
2. A Partner API credential with events:write and batches:read. Confirming a supplier's shipment needs a production credential (sandbox and production).
3. The mapping, confirmed once and updated when a customer or supplier is added:

{
  "company": "ACME",
  "gtin_field": "U_GTIN",
  "customers": {
    "C-LAKESIDE": {"schema_name": "lakeside"},
    "C-CLINIC": {"name": "Hope Clinic", "ppb_licence": "PF-0042",
                 "email": "orders@hope.example", "phone": "+254700000042"}
  },
  "suppliers": {
    "V-MAKER": {"name": "Maker Pharmaceuticals", "ppb_licence": "PPB/M/1",
                "email": "qa@maker.example", "phone": "+254700000001"},
    "V-DISTRIB": {"on_dawatrack": true, "name": "Distrib Ltd"}
  }
}

• A customer on DawaTrack is named by its facility. One outside DawaTrack is named by name or PPB licence, with an email and a phone: that is how its confirmation link and any recall reach it, and both are kept off the ledger.
• A supplier that declares its shipments on DawaTrack is on_dawatrack: your receipt confirms its waiting shipment. Two or more waiting shipments of the same batch stop the line: confirm it on the portal instead.

The run report

Each run ends with a report of what it wrote, what it had already written, what it retracted, and every line it didn't write, grouped by what you fix: customers and suppliers to map, items without a GTIN, lines without their batch, quantities to correct, stock with no receipt yet, and DawaTrack's refusals.

Known limits

• Batch details missing from some Service Layer responses. SAP's support notes describe responses for documents such as deliveries without their batch and serial details in some cases. If your version does this, those lines stop (the batch isn't guessed) until it is fixed with your SAP partner.
• One event per call: a shipment must name a receipt written earlier in the same run. At the Partner API's default limit of 5000 requests a day (rate limits), a day's run fits about that many events; a company that needs more is given its own limit.
• Other ERPs: no ready connector. They connect through the Partner API directly (quickstart).