Legacy Integration — Zwerfkei Backoffice (legacy) & Navision 2018¶

This page documents how the current (legacy) Zwerfkei platform integrates with Microsoft Dynamics Navision 2018 via the K3 Retail / LS Retail extension. It serves as reference material during the migration to the new architecture.

Architecture¶

The integration is a two-way, SOAP-based sync between Zwerfkei Backoffice (legacy) and Navision. Two separate patterns are used:

• Inbound (NAV → Web): Continuous polling — a cron job calls Navision's sync buffer every minute and pulls any changed records.
• Outbound (Web → NAV): Queue-based — the application writes a pending record to the k3_synchronization table; a separate cron processes the queue and calls the appropriate SOAP operation.

sequenceDiagram
    participant Cron as Cron: k3retail_webservices
    participant Buffer as NAV Sync Buffer
(GetSyncBuffer)
    participant NAV as Navision 2018 SOAP
    participant DB as Zwerfkei DB
(k3_* tables)
    participant Queue as k3_synchronization
(outbound queue)
    participant Sender as Cron: k3retail_sync

    loop Every minute (50 sec inner loop)
        Cron->>Buffer: GetSyncBuffer
        Buffer-->>Cron: Changed record list
        loop For each changed record
            Cron->>NAV: GetProduct / GetSalesPrice / etc.
            NAV-->>Cron: Record data
            Cron->>DB: Upsert k3_* table
        end
    end

    Note over Queue,Sender: Outbound queue processing
    DB->>Queue: App writes pending record
(model, action, reference)
    loop Every 5 minutes
        Sender->>Queue: Read pending records
        Sender->>NAV: SubmitOrder / SetMemberAccount / etc.
        NAV-->>Sender: nav_id / confirmation
        Sender->>Queue: Mark status = ok
    end

Three WSDL services¶

The integration uses three separate SOAP endpoints on the Navision server:

WSDL definitions are cached locally and refreshed hourly.

Data flows¶

Inbound sync — buffer pattern¶

All inbound sync flows through the GetSyncBuffer call. Navision queues every changed record internally; the website polls this queue continuously.

1. Call GetSyncBuffer → NAV returns a list of changed records with table number and record ID.
2. For each record, call the appropriate Get* operation by table number:

1. Map the response to the local k3_* model and upsert in the database.
2. Acknowledge the buffer entry so Navision doesn't resend it.

Outbound sync — queue pattern¶

Changes that need to be sent to Navision (orders, customer updates, discount edits) follow a queue pattern:

1. The application creates a row in k3_synchronization with status = pending.
2. The k3retail_sync cron reads pending rows and calls the appropriate SOAP operation.
3. On success: status = ok, nav_id is stored back on the record.
4. On failure: retry counter incremented; up to 10 attempts before marking as error.

A database lock (GET_LOCK('k3_sync', 1)) prevents concurrent outbound runs.

Connection & error handling¶

• Authentication: HTTP Basic Auth (username + password) via SoapClient.
• Timeout: 30-second socket timeout per call.
• Retries: Up to 10 attempts per call.
• Error locking: On SOAP fault, a 5-minute cooldown lock prevents retry storms.
• Monitoring: checkK3Sync cron validates queue completeness and sends an alert email if records are stuck.

Kei endpoints — relevance decision¶

Per ZWE-392's DoD, the checked Kei endpoints (real usage evidence from the ERP administrator's log-based inventory) were reviewed for new-webshop relevance:

• Rejected as not webshop-relevant: PhysInventory, GetOpenPhysInventory, GetPurchaseHeader, GetPurchaseLine, CreateMembershipCards — purchasing and physical-inventory administration, not webshop concerns.
• Confirmed real, but out of scope for now: GetMemberAccount, SetMemberAccount, CreateMemberAccount, GetMemberPointEntry — genuinely active loyalty/membership infrastructure (see Core Webshop Endpoints's note on GetPeriodicDiscount's MemberPoints link), but decoupled from the current order-submit/order-status scope. Whether/how membership integrates with the new backend is deferred as a future migration decision, not part of this milestone.

Related pages¶

Sync Triggers & Cron Methods K3 Data Models ERP Sync Diagrams Business Central (new platform)