Agent configuration reference

Most of the ERP Sync agent’s behavior is set in Omnilinker, on the connection’s sync configuration, and the agent downloads it. See Sync configuration. The local settings on this page are for the machine the agent runs on. You rarely need to change them.

Where the agent gets its configuration

Source	What it holds
`credentials.dat`	The API key, API URL, connection, organization ID, ERP database settings and company ID. Written by the setup wizard and the tray app’s Settings…. This is the only place the agent reads the API key, connection and database settings from.
Omnilinker (cloud)	The connection’s sync configuration: what to sync, intervals, batch sizes, field mappings. The agent fetches it every 5 minutes and keeps a copy in `config-cache.json` for when Omnilinker cannot be reached.
`appsettings.json`, `ErpSync` and `Updates` sections	Local, machine-level settings, described below.
Environment variables	Override `appsettings.json` values.

For the settings in appsettings.json, the order of precedence is, highest first:

Command-line arguments.
Environment variables, named <Section>__<Setting>, for example ErpSync__PollingIntervalSeconds or Updates__Channel.
appsettings.json in the install folder.
The built-in defaults listed below.

Where a setting also exists in the cloud configuration or in credentials.dat, that value wins. Each setting below says so.

ApiKey and ConnectionId in appsettings.json and in environment variables are ignored. The agent takes the API key and connection only from credentials.dat. Configure them with the setup wizard.

Change a setting

Set the value as a machine environment variable, in PowerShell as Administrator, then restart the service. The service reads these settings only when it starts:

[Environment]::SetEnvironmentVariable("ErpSync__PollingIntervalSeconds", "120", "Machine")
Restart-Service OmnilinkerErpSyncService

You can also edit appsettings.json in the install folder, by default C:\Program Files\Omnilinker\ErpSync\current, as an administrator, and restart the service.

Every update replaces appsettings.json, and the agent updates itself at night. A change you made in the file is then lost without notice. Environment variables are not affected by updates, so prefer them.

The shipped file looks like this (its Logging section is left out):

appsettings.json

{
  "ErpSync": {
    "ApiUrl": "https://omnilinker.pl",
    "LocalApiPort": 5555,
    "PollingIntervalSeconds": 60,
    "OutboxBatchSize": 100,
    "OutboxPublishIntervalSeconds": 5,
    "MaxRetryAttempts": 5,
    "AutoUpdateEnabled": true,
    "ConnectionId": null,
    "ApiKey": null,
    "PluginsPath": "plugins"
  },
  "Updates": {
    "FeedUrl": "https://releases.omnilinker.com/erpsync",
    "Channel": "stable"
  }
}

Settings

“Default” is the value the agent uses when the setting is missing from appsettings.json.

Cloud connection

Setting	Type	Default	Meaning
`ApiUrl`	string	`https://omnilinker.pl`	Omnilinker’s address. The API URL saved by the setup wizard in `credentials.dat` takes precedence, so this value is used only before the wizard has run. Change the URL in Settings… instead.
`ApiKey`	string	`null`	Ignored. See the note above.
`ConnectionId`	GUID	`null`	Ignored. See the note above.

Local API

Setting	Type	Default	Meaning
`LocalApiPort`	integer	`5555`	The port of the agent’s local API. It listens on `localhost` only.

Leave LocalApiPort at 5555. Omnilinker’s web app and the tray app’s fallback connection both expect the local API on port 5555 and do not read this setting.

Change detection

Setting	Type	Default	Meaning
`PollingIntervalSeconds`	integer	`60`	How often the polling cycle runs, in seconds. In hash scan mode this is how quickly a Sync Now request is picked up.
`HashCheckIntervalSeconds`	integer	`900`	Seconds between hash checks, used only until the cloud configuration has loaded. After that, the connection’s hash check interval applies.
`HashCheckInitialDelaySeconds`	integer	`120`	Seconds to wait after the service starts before the first hash check.
`HashCheckFetchBatchSize`	integer	`100`	How many changed records a hash check reads from the ERP at a time.

Sending to Omnilinker

The agent queues every change in a local outbox and sends it to Omnilinker in batches.

Setting	Type	Default	Meaning
`OutboxBatchSize`	integer	`500`	Maximum events per batch. The shipped `appsettings.json` sets `100`. The connection’s sync configuration takes precedence when it sets a batch size.
`CloudApiBatchHardLimit`	integer	`1000`	Upper limit for events per request, whatever the other settings say. Omnilinker accepts at most 1,000 events per request, so do not raise it.
`OutboxDrainThreshold`	integer	`1000`	When more events than this are waiting, the agent sends batches back to back, without the pause between them, until the backlog is cleared.
`OutboxPublishIntervalSeconds`	integer	`5`	Seconds between send cycles, used only until the cloud configuration has loaded. After that, the connection’s value applies.
`MaxRetryAttempts`	integer	`5`	How many times the agent tries to send an event before marking it as failed.

Plugins

Setting	Type	Default	Meaning
`PluginsPath`	string	`plugins`	Reserved. It has no effect yet: the agent does not load providers from a plugins folder. The Wapro provider is built in.

Updates

How the agent updates itself. AutoUpdateEnabled is in the ErpSync section. The others are in the Updates section, so their environment variables start with Updates__.

Setting	Type	Default	Meaning
`AutoUpdateEnabled`	boolean	`true`	`false` turns automatic updates off. You then update by hand.
`FeedUrl`	string	none	Where the agent looks for new versions. The shipped file sets `https://releases.omnilinker.com/erpsync`. Empty turns updates off. Do not change it.
`Channel`	string	none	Which releases the agent takes. The shipped file sets `stable`.
`CheckEvery`	time span	`04:00:00`	How often the agent looks for a new version.
`FirstCheckAfter`	time span	`00:05:00`	How long after the service starts it looks for the first time.
`ApplyFrom`	time of day	`01:00`	Start of the nightly window in which a downloaded version is installed, in the computer’s local time.
`ApplyUntil`	time of day	`05:00`	End of that window. The window can run past midnight, for example `22:00` to `04:00`.

A version is installed only inside the window and only when no sync is running. If installing fails, the agent tries again the next night.

Fixed values

The agent has these settings internally, but does not read them from appsettings.json or environment variables. They always have the values shown. They are listed so you can interpret the agent’s logs.

Setting	Value	Meaning
`OutboxPublisherStartupDelaySeconds`	`10`	Seconds after start-up before the first send cycle.
`PhaseAdvanceFailedGraceMinutes`	`30`	With WFM_INT change tracking, how long a sync phase waits on events that failed all retries before moving on with a warning.
`ChangeConsumptionIntervalSeconds`	`60`	With WFM_INT change tracking, seconds between cycles that read changes from the ERP.
`ChangeConsumptionStartupDelaySeconds`	`5`	Seconds after start-up before the first WFM_INT cycle.
`ChangeConsumptionCycleBudgetSeconds`	`45`	Time limit per change stream per WFM_INT cycle, so one busy stream cannot hold up the others.
`HeartbeatIntervalSeconds`	`60`	Seconds between heartbeats to Omnilinker.
`CapabilitiesRefreshIntervalSeconds`	`600`	How often the agent checks again what the ERP supports, in seconds.
`ReferenceSyncIntervalSeconds`	`86400`	How often the ERP’s reference (dictionary) data is uploaded again: daily.
`ReferenceChunkSize`	`500`	Reference items per upload.
`BundleCompositionSyncIntervalSeconds`	`21600`	How often bundle compositions are read in full: every 6 hours.
`ReconciliationIntervalSeconds`	`604800`	With WFM_INT change tracking, how often a full reconciliation check runs: every 7 days.

Logging

The service writes one log file per day to %ProgramData%\Omnilinker\ErpSync\logs (see Local files) and keeps the last 30 files. Each line has a timestamp, the level, the component and the message. Setup, updates and uninstalling add to setup.log in the same folder: done, or one line for each step they could not complete. The log level is fixed: Information for the agent, Warning for framework components. The Logging section in appsettings.json has no effect on the log files.

Local files

The agent keeps three folders on the machine. Install folder: C:\Program Files\Omnilinker\ErpSync\current when you install as described in Install the agent. Setup replaces its contents on every update.

File	Contents
`Omnilinker.ErpSync.Service.exe`	The Windows service.
`tray\Omnilinker.ErpSync.Tray.exe`	The tray app, in a subfolder of its own.
`appsettings.json`	The settings on this page. Replaced on every update.
`install-service.ps1`, `uninstall-service.ps1`	Only for a portable copy. Setup does not need them.

Data folder: %ProgramData%\Omnilinker\ErpSync, usually C:\ProgramData\Omnilinker\ErpSync. The service and everyone who uses the tray app see the same folder. Setup lets only SYSTEM and administrators change it. Other users can read it.

File	Contents
`credentials.dat`	API key, API URL, connection, organization ID, ERP database settings and company ID. Encrypted with Windows DPAPI, machine scope: it can be decrypted only on this computer. Only SYSTEM and administrators can open the file.
`logs\erpsync-<yyyyMMdd>.log`	Service log files, one per day, 30 kept. For example `erpsync-20260927.log`.
`logs\setup.log`	What setup, updates and uninstalling could not do.

Service profile folder: C:\Windows\System32\config\systemprofile\AppData\Local\Omnilinker\ErpSync, the local application data folder of Local System, which the service runs as.

File	Contents
`erpsync.db`	Local SQLite database: the outbox of events waiting to be sent, the local sync log, and the agent’s change-detection state. `erpsync.db-wal` and `erpsync.db-shm` next to it belong to it.
`config-cache.json`	The last cloud configuration the agent received, used when Omnilinker cannot be reached at start-up.

Do not delete erpsync.db while the agent is installed. Events that have not been sent yet are lost, and the agent has to rebuild its change-detection state.

Get started

Set up

Configure sync

Operate

Providers

Reference

Agent configuration reference

Where the agent gets its configuration

Change a setting

Settings

Cloud connection

Local API

Change detection

Sending to Omnilinker

Plugins

Updates

Fixed values

Logging

Local files

​Where the agent gets its configuration

​Change a setting

​Settings

​Cloud connection

​Local API

​Change detection

​Sending to Omnilinker

​Plugins

​Updates

​Fixed values

​Logging

​Local files

Where the agent gets its configuration

Change a setting

Settings

Cloud connection

Local API

Change detection

Sending to Omnilinker

Plugins

Updates

Fixed values

Logging

Local files