> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnilinker.pl/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the ERP Sync agent

> Install the ERP Sync agent on a Windows machine, decide who can change it, and update or remove it later.

The ERP Sync agent is one installation package that contains both parts of the agent:

* **The Windows service** (`Omnilinker.ErpSync.Service.exe`). It reads your ERP database and sends changes to
  Omnilinker. It runs as Local System.
* **The tray app** (`tray\Omnilinker.ErpSync.Tray.exe`). You use it to configure the agent and watch what it is
  doing. It runs as the person who is signed in.

Setup does the whole installation: it copies the files, registers and starts the Windows service, prepares the
agent's data folder, and makes the tray app start for everyone who signs in. You do not run any script.

## Before you begin

* Create the connection in Omnilinker and copy its agent API key. See [Create a connection](/erp/create-connection).
* Check the machine against the [requirements](/erp/requirements).
* You need a local administrator account, and a PowerShell window started **as Administrator**.
* Decide who will configure the agent from the tray app. Setup gives you that right. Other people need to be added
  to a local group. See [Who can change the agent](#who-can-change-the-agent).

## Install the agent

<Steps>
  <Step title="Run setup for all users">
    Open PowerShell **as Administrator** in the folder that contains the installer, and run it with these options.
    Replace `<installer>` with the installer's file name:

    ```powershell theme={null}
    .\<installer>.exe --silent --installto "C:\Program Files\Omnilinker\ErpSync"
    ```

    Setup installs the agent to `C:\Program Files\Omnilinker\ErpSync\current`. This is the **install folder**. It
    contains the service, `appsettings.json`, and the tray app in its own `tray` subfolder.

    <Warning>
      Do not double-click the installer. Without `--installto`, it installs into your own user profile
      (`%LocalAppData%\OmnilinkerErpSync`). The service runs as Local System, so setup refuses to register it from a
      folder that a signed-in person can change: anyone who could replace its files could run code as SYSTEM.
      The files are copied, but there is no service.
    </Warning>
  </Step>

  <Step title="Let setup register the agent">
    Setup then does the following by itself:

    | What                | Details                                                                                                                                                                                                         |
    | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Windows service     | Name `OmnilinkerErpSyncService`, display name **Omnilinker ERP Sync**, description "Synchronizes data between your ERP system and Omnilinker cloud".                                                            |
    | Startup type        | Automatic.                                                                                                                                                                                                      |
    | Log on as           | Local System.                                                                                                                                                                                                   |
    | Recovery            | Restart after 5 seconds, then 10 seconds, then every 30 seconds. The failure count resets after one day. This also applies when the service stops with an error, which is how an update restarts it.            |
    | Data folder         | Creates `%ProgramData%\Omnilinker\ErpSync`. Only SYSTEM and administrators can change it; other users can only read it, for example the log files. See [Local files](/erp/configuration-reference#local-files). |
    | Operators group     | Creates the local group **Omnilinker ERP Sync Operators** and adds you to it.                                                                                                                                   |
    | Tray app at sign-in | Adds `OmnilinkerErpSyncServiceTray` under `HKLM\Software\Microsoft\Windows\CurrentVersion\Run`, so the tray app starts for everyone who signs in to this computer.                                              |

    Finally, setup starts the service. The service starts the tray app for everyone who is signed in, and the
    [setup wizard](/erp/setup-wizard) opens.

    If a service called `OmnilinkerErpSyncService` already exists, for example from an earlier version, setup
    updates its program path and startup type and keeps its other settings, including its **Log On** account.
  </Step>

  <Step title="Check the result">
    ```powershell theme={null}
    Get-Service OmnilinkerErpSyncService
    ```

    `Status` should be `Running`.

    Setup does not stop when one of its steps fails. It writes what it could not do to
    `%ProgramData%\Omnilinker\ErpSync\logs\setup.log`, one line per problem. A successful run writes `done`.

    ```powershell theme={null}
    Get-Content "$env:ProgramData\Omnilinker\ErpSync\logs\setup.log" -Tail 20
    ```

    To fix a problem, run the same setup command again from PowerShell as Administrator. Every step can run again
    safely. See [Troubleshooting](/erp/troubleshooting).
  </Step>
</Steps>

## Who can change the agent

Anyone signed in to the agent computer can open the tray app and see the agent's status, logs and settings. The
password and API key are never shown.

Changing the agent needs more. Only these people can save settings, run the setup wizard, test the database
connection, enable or disable change tracking, pause syncing, and pause or cancel a hash check from the tray app:

* members of the local group **Omnilinker ERP Sync Operators**,
* administrators whose tray app runs elevated (**Run as administrator**).

Anyone else sees "Only an administrator of this PC can do that." Setup adds the person who installed the agent to
the group. To add someone else, run in PowerShell as Administrator:

```powershell theme={null}
net localgroup "Omnilinker ERP Sync Operators" "<DOMAIN\user>" /add
```

The change takes effect straight away. The person does not need to sign out.

You can also manage the group in **Computer Management** > **Local Users and Groups** > **Groups**.

## Next step

Complete the [setup wizard](/erp/setup-wizard). It opens by itself after installation. If it does not, start the
tray app from the `tray` subfolder of the install folder.

## Update the agent

The agent updates itself. The service looks for a new version 5 minutes after it starts and then every 4 hours.
When it finds one, it downloads it straight away and installs it at night, between 01:00 and 05:00 local time, when
no sync is running. It then stops, and Windows starts the new version a few seconds later.

An update runs the same steps as setup, so the service, the operators group and the tray app at sign-in stay in
place. The tray app closes while its files are replaced. The service starts it again for everyone who is signed in.

What an update keeps and replaces:

* Your credentials, queue and logs are kept. They are stored outside the install folder.
* `appsettings.json` in the install folder is replaced by the new version's file. Set the values you change as
  machine environment variables instead. See [Change a setting](/erp/configuration-reference#change-a-setting).

To turn automatic updates off, set `AutoUpdateEnabled` to `false`. See
[Updates](/erp/configuration-reference#updates). The tray app has no update button.

To update by hand, run the new version's installer with the same command as for the first installation, from
PowerShell as Administrator.

## Upgrade from an earlier version

Earlier versions installed into the installing person's profile and needed `install-service.ps1` to register the
service. Some installations also changed the service's **Log On** account. To move such an installation to the
current model:

<Steps>
  <Step title="Let the queue empty">
    Check that no events are waiting to be sent: `pending` should be `0` in the tray app's status window or in
    `GET /api/sync/outbox/stats` on the [local API](/erp/local-api). The queue is not moved to the new installation.
  </Step>

  <Step title="Remove the old service and app">
    Exit the tray app. In PowerShell as Administrator, run `uninstall-service.ps1` from the old install folder. Then,
    signed in as the account that installed the old version, uninstall it in **Settings** > **Apps** >
    **Installed apps**.
  </Step>

  <Step title="Install the new version">
    Follow [Install the agent](#install-the-agent).
  </Step>

  <Step title="Check the configuration">
    If the old service ran as Local System, the new service moves its saved configuration to the new data folder
    on first start, and the setup wizard does not open. If the old service ran under another account, its
    configuration stays in that account's profile. Complete the [setup wizard](/erp/setup-wizard) again.

    After that you can delete the old data folder, `%LocalAppData%\Omnilinker\ErpSync` of the account the old service
    ran as.
  </Step>
</Steps>

The new service starts with an empty local database, so it rebuilds its change-detection state, as after a new
installation.

## Remove the agent

<Steps>
  <Step title="Uninstall the app">
    Signed in as the administrator who installed the agent, open **Settings** > **Apps** > **Installed apps** (on
    Windows 10: **Apps & features**) and uninstall **Omnilinker ERP Sync**.

    Uninstalling stops and removes the Windows service, removes the tray app from sign-in, and deletes the install
    folder. Problems are written to `setup.log`, as during installation.
  </Step>

  <Step title="Delete local data (optional)">
    Uninstalling keeps the agent's data, for support and in case you reinstall:

    * `%ProgramData%\Omnilinker\ErpSync`: the encrypted credentials and the log files.
    * `C:\Windows\System32\config\systemprofile\AppData\Local\Omnilinker\ErpSync`: the local queue and the cached
      configuration.

    Delete both folders, as an administrator, if you are not reinstalling the agent on this computer. Events still
    waiting in the queue are lost.
  </Step>

  <Step title="Remove the operators group (optional)">
    Uninstalling keeps the **Omnilinker ERP Sync Operators** group. To remove it, run in PowerShell as Administrator:

    ```powershell theme={null}
    net localgroup "Omnilinker ERP Sync Operators" /delete
    ```
  </Step>
</Steps>

To stop a copy of the agent you cannot reach from signing in to Omnilinker, generate a new agent key for the
connection. There is no separate revoke action: generating a key revokes the previous one immediately. See
[Create a connection](/erp/create-connection).

## Portable copy (ZIP)

The package also ships `install-service.ps1` and `uninstall-service.ps1`, for a copy unpacked from a ZIP file
instead of installed with setup. Use setup whenever you can. The script only registers the service (as Local
System, automatic start, restart after a crash, display name **Omnilinker ERP Sync Service**). It does not create
the operators group, does not restrict the data folder, and does not start the tray app at sign-in. Without the
group, only an administrator running the tray app elevated can change the agent.

Unpack the copy to a folder outside any user profile, for example `C:\Program Files\Omnilinker\ErpSync`, then run
in PowerShell as Administrator, from that folder:

```powershell theme={null}
powershell -ExecutionPolicy Bypass -File .\install-service.ps1
```

`uninstall-service.ps1` stops the service, waits up to 30 seconds for it to stop (then ends the process), and
deletes it.