Setting Up ERP Sync

Kolva connects to your ERP through a lightweight on-premise agent. This guide covers installation for Sage X3 and SAP Business One, API key configuration, sync settings, monitoring, and troubleshooting.

How the Agent Works

The Kolva agent is a self-contained binary with no runtime dependencies. It runs on a machine inside your network, reads data from your ERP's database, and pushes it to Kolva over HTTPS. Key security properties:

• Outbound only — All traffic goes from your network to Kolva. No inbound ports, no VPN, no firewall exceptions required.
• Encrypted — All data is transmitted over TLS 1.3.
• API key authentication — The API key is stored locally; only its SHA-256 hash is stored on Kolva's servers.
• Read-only — The agent only reads data from your ERP. It never writes, modifies, or deletes anything.

Installing the Sage X3 Agent

1. Go to Settings > Integrations > ERP and select Sage X3.
2. Download the agent for your operating system (Windows or macOS).
3. Extract the archive and run the setup wizard.
4. Enter your SQL Server connection string (host, port, database, credentials with SELECT-only access).
5. The wizard generates an API key. Copy and save it securely — it is shown only once.
6. Run kolva-agent --discover to verify connectivity and see available entities (customers, items, invoices).
7. Run kolva-agent --sync for the initial data load.

Installing the SAP Agent

1. Go to Settings > Integrations > ERP and select SAP Business One.
2. Download the agent for your operating system.
3. Run the setup wizard on port 3848.
4. Enter your SAP OData REST API endpoint and service credentials.
5. The wizard tests the connection and generates an API key.
6. Run kolva-agent --discover to list available entities (BusinessPartners, Items, Invoices).
7. Run kolva-agent --sync to start the initial data import.

Configuring Sync Frequency & Data Scope

After the initial sync, you can configure how often the agent runs and how much historical data it pulls:

• Daemon mode — Run kolva-agent --daemon to sync continuously in the background. The agent checks for changes at configurable intervals (default: every 15 minutes).
• Scheduled sync — Alternatively, set up a cron job (Linux/macOS) or Windows Task Scheduler to run the agent on your preferred schedule.
• Data scope — By default, Kolva imports the last 36 months of financial data, 24 months of orders/deliveries, and 12 months of stock movements. Adjust these in Settings > Integrations.

Monitoring Sync Status

Track the health of your ERP connection from the Kolva dashboard:

1. Go to Settings > Integrations to see the status of each connected agent.
2. A green indicator means the agent synced successfully within the expected interval.
3. A yellow indicator means the agent is overdue — it has not synced in longer than expected.
4. A red indicator means the last sync failed. Click for error details.
5. View the sync history log showing timestamps, record counts, and any errors for each sync run.

Troubleshooting Common Issues

• Agent cannot connect to database — Verify the connection string, ensure the SQL user has SELECT permissions, and confirm the database server allows connections from the agent's machine.
• Agent cannot reach Kolva — Ensure outbound HTTPS (port 443) to api.kolva.ai is allowed by your firewall and proxy.
• Data appears incomplete — Check the data scope settings. Some records may fall outside the configured time window. Open invoices with remaining balances always sync regardless of age.
• Duplicate records — The agent uses external IDs (sage_x3:* or sap:*) to deduplicate. If you see duplicates, verify that the ERP record IDs are unique.