> For the complete documentation index, see [llms.txt](https://sealights-docs.tricentis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sealights-docs.tricentis.com/setup-and-configuration/upgrading-abap-agent-version.md).

# Upgrading ABAP Agent version

When a new ABAP Agent release is available, it is distributed at the same download location as the original installation. See [Broken mention](broken://pages/w85d1VmxjGySkx1apr1N).

Before upgrading, review the [ABAP Agent release notes](https://docs.sealights.io/knowledgebase/agent-release-notes/abap-technologies/abap-agent) for version-specific changes and authorization requirements.

## Compatibility with earlier ABAP Agent versions

{% hint style="danger" %}
**ABAP Agent 2.0 is not compatible with ABAP Agent 1.3.0.70 and earlier.**

You cannot continue using your existing 1.3 installation, SAP add-on, local agent data, or SeaLights application history with 2.0.

Any move from **1.3.x** to **2.0** (including versions above 1.3.0.70) still requires the new SAP add-on and a full rebuild path — not an in-place continuation of 1.3 data.

* The **new SAP add-on** for 2.0 is **not backwards compatible** with earlier agent versions.
* Your agent configuration must be valid for the current configuration schema version. Reconfigure as needed.
* Discard prior local agent build and graph data. Do not reuse local databases or coverage artifacts from 1.3.
* You must run a **full** initial build map for each pipeline.
* Create a **new SeaLights application**. Do not reuse your 1.3 application or its history.
  {% endhint %}

**Required actions when moving to ABAP Agent 2.0:**

1. Install the new ABAP Agent 2.0 SAP add-on on your SAP landscape (it replaces the previous add-on and is not backwards compatible).
2. Install ABAP Agent 2.0 and ensure your configuration is valid for the current schema version (migrate and/or reconfigure as needed).
3. Discard prior local agent build and graph data — do not reuse 1.3 local databases or coverage artifacts.
4. Create a **new** SeaLights application for each pipeline. Do not reuse the 1.3 application or its history.
5. Run a **full** initial build map for each pipeline before relying on coverage or test-impact results.

{% hint style="info" %}
The ABAP Agent relies on scheduled tasks using the Windows Task Scheduler. Those tasks must be stopped before upgrading. See below.
{% endhint %}

{% hint style="danger" %}
BUILDMAP tasks only run once. If they succeeded, they can be removed from the Windows Task Scheduler.
{% endhint %}

## Upgrading from 2.0 or 2.0.1 to 2.1

Use this section when you are on ABAP Agent **2.0** or **2.0.1** and installing **2.1** (for example release build **2.1.2.175**).

1. Follow [Stop scheduled tasks](#1-stop-scheduled-tasks) and [Stop the ABAP Agent Server](#2-stop-the-abap-agent-server) below.
2. Run `SeaLights_ABAP_Agent_Setup.exe` over the existing installation. Setup force-replaces all packaged files under the installation `bin` directory so equal-version or stale binaries do not survive the upgrade.
3. After installation, run [Restart the ABAP Agent Server](#4-restart-the-abap-agent-server) and [Re-enable scheduled tasks](#5-re-enable-scheduled-tasks).
4. Run `slabapcli setup status` to verify health.

Your `config.toml`, logs, and `%ProgramData%\Tricentis\SeaLights\ABAP Agent` userdata remain in place. No full Initial Build Map rerun is required solely for the 2.1 upgrade unless release notes or support direct you to rebuild.

{% hint style="warning" %}
**First Build Modifications run after upgrading to 2.1:** the SAP tables cache files are stamped with a cache format version. When the agent finds a cache written by an earlier format, the first `BUILD_MODS` run for that pipeline rebuilds the tables cache in full instead of refreshing it incrementally. Expect this run to take longer than usual. Later runs return to incremental refresh.
{% endhint %}

{% hint style="info" %}
2.1 adds incremental Build Mods cache/link refresh, Most-at-Risk data from the Initial Build Map and Build Mods, Octane and CALM adapters, and service hot-reload for most lab settings (with `sealights.token` still requiring a service restart). See [What's new in 2.1](https://sealights-docs.tricentis.com/setup-and-configuration/pages/vSmHtyl7vPTk4tnsx7Gi#whats-new-in-2.1).
{% endhint %}

## Upgrading from a prior ABAP Agent 2.0 build

Use this section when you are already on ABAP Agent 2.0 and installing a newer 2.0.x or 2.1 build.

### 1. Stop scheduled tasks

1. Open **Windows Task Scheduler**.
2. Under the **SeaLights** directory, select all **FOOTPRINTS** and **BUILDMODS** tasks.
3. Make sure none of those tasks are actively processing:
   * **FOOTPRINTS**: No tests are currently running.
   * **BUILDMODS**: No transports are currently being imported.
4. Click **End**, then click **Disable** on each selected task.

### 2. Stop the ABAP Agent Server

Stop the **SeaLights ABAP Server** Windows service before running the installer:

{% tabs %}
{% tab title="Command Prompt" %}
{% code overflow="wrap" lineNumbers="true" %}

```batch
slabapcli.exe server stop
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```powershell
.\slabapcli.exe server stop
```

{% endcode %}
{% endtab %}
{% endtabs %}

Completing active tests and transports, ending and disabling the scheduled tasks above, and stopping the server with `slabapcli server stop` are required preparation before Setup. The installer can still detect leftover lock holders and ask to stop them, but that prompt is final protection — not a substitute for finishing in-flight work or preventing scheduled tasks from respawning.

### 3. Run the installer

Download the latest agent ZIP file and extract the installer. Run `SeaLights_ABAP_Agent_Setup.exe` as an administrator over the existing installation.

Setup follows a stop-then-replace sequence:

1. It checks for the `SLABAPServer` Windows service and for `SLABAPServer.exe`, `SLABAPAdapterHost.exe`, or `watcher.exe` running from the selected installation's `bin` directory (not every similarly named process on the machine).
2. In an interactive install, Setup asks whether to stop those processes and continue.
3. Choosing **Yes** stops the lock holders and continues. Choosing **No**, or a failure to stop them, aborts installation before any files are replaced.
4. In a silent install, Setup does not show the prompt: it automatically attempts the same stop and continues only if stopping succeeds; otherwise installation aborts.

After lock holders are stopped, Setup replaces **all packaged agent files under the installation `bin` directory**, including files whose installed version matches the packaged version. Replacement covers the packaged agent payload only — it does not remove arbitrary orphan or customer-added files under `bin`, and it does not wipe `%ProgramData%\Tricentis\SeaLights\ABAP Agent`. Configuration (`config.toml`), logs, and public and private userdata remain in place; Setup migrates the existing configuration after file replacement.

The installer then automatically runs `setup migrate --yes` (to bring `config.toml` to the current schema version) and `setup upgrade` (to restore the **SeaLights ABAP Server** service and the agent's scheduled tasks to the state they were in before the upgrade). You do not need to run either command yourself.

{% hint style="warning" %}
**`setup migrate` is for ABAP Agent 2.0+ configuration schema only.** It updates an existing 2.0 `config.toml` to the current schema version (6). It is **not** a supported product migration from ABAP Agent 1.3 to 2.0. For 1.3 and earlier, see [Compatibility with earlier ABAP Agent versions](#compatibility-with-earlier-abap-agent-versions).
{% endhint %}

### 4. Restart the ABAP Agent Server

After the installer completes, start the service again. You stopped it in step 2, so the installer records it as stopped and does not restart it for you:

{% tabs %}
{% tab title="Command Prompt" %}
{% code overflow="wrap" lineNumbers="true" %}

```batch
slabapcli.exe server start
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```powershell
.\slabapcli.exe server start
```

{% endcode %}
{% endtab %}
{% endtabs %}

See [Start the ABAP Agent Server](broken://pages/jjXJbDJ9CnFBYzl2NDMP).

### 5. Re-enable scheduled tasks

1. In **Windows Task Scheduler**, select the same **FOOTPRINTS** and **BUILDMODS** tasks.
2. Click **Enable**, then click **Run**.

### 6. Verify the upgrade

Run the following to confirm all components are healthy:

{% tabs %}
{% tab title="Command Prompt" %}
{% code overflow="wrap" lineNumbers="true" %}

```batch
slabapcli.exe setup status
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```powershell
.\slabapcli.exe setup status
```

{% endcode %}
{% endtab %}
{% endtabs %}

See [Validate Your Setup](broken://pages/A8FSceuQXginyDTL5f4z) for interpreting the output.

***

## Migrating the configuration schema (2.0+ only)

If the installer does not run `setup migrate` (for example, in a manual or scripted 2.0 deployment), bring an existing **2.0** `config.toml` to the current schema version (6) yourself:

{% tabs %}
{% tab title="Command Prompt" %}
{% code overflow="wrap" lineNumbers="true" %}

```batch
slabapcli.exe setup migrate
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```powershell
.\slabapcli.exe setup migrate
```

{% endcode %}
{% endtab %}
{% endtabs %}

Add `--yes` (`-y`) to suppress interactive confirmation prompts:

{% tabs %}
{% tab title="Command Prompt" %}
{% code overflow="wrap" lineNumbers="true" %}

```batch
slabapcli.exe setup migrate --yes
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```powershell
.\slabapcli.exe setup migrate --yes
```

{% endcode %}
{% endtab %}
{% endtabs %}

For full details on what `setup migrate` does and how it transforms the configuration file, see [Migrate a legacy configuration](broken://pages/NRR5ldRJ84vbe7IcN65N) and [Configuration settings](broken://pages/DZM4uWEu5r51kMDWCmDB).

***

## Restoring scheduled tasks

The installer runs `slabapcli setup upgrade` automatically at the end of every upgrade. It restores the **SeaLights ABAP Server** service and each agent scheduled task to the state recorded before the files were replaced: a service that was running is started again, and tasks that were enabled are enabled again. Tasks that were disabled before the upgrade stay disabled. You do not need to run `setup upgrade` yourself.

If the upgrade does not complete, the agent's scheduled tasks stay disabled. Rerun the installer, or re-enable the tasks in **Windows Task Scheduler** after you resolve the problem.

{% hint style="info" %}
When you stop or replace a scheduled task through agent task management (for example with `slabapcli`), the agent disables the task, asks Task Scheduler to stop any running instance, waits up to 10 seconds for the watcher to exit, and then deletes the task. If the watcher has not exited by then, the agent logs a warning that a watcher instance may still be running; check for a leftover `watcher.exe` process before continuing. That cleanup is separate from the installer process-stop prompt described above.
{% endhint %}