Upgrading from the Legacy Connector¶
For sites running the legacy connector, version 4.5.2, and moving to the current release. The
move is a one-time step with more care than usual. Once you are on the current line, updates follow
Seeq's releases in smaller, more frequent, lower-risk steps.
The upgrade is done in one working session, with your team and EEI on the same call, and one interruption of the connector's service. You send some information beforehand through a support ticket; in the session you follow this page step by step while EEI follows its own checklist for the same steps. Keep this page open during the session: the step labels (Window 3, Credentials 2) are how everyone on the call refers to where you are.
Why upgrade, if the features are the same¶
The day-to-day features have not changed: the same tags, asset tree and signals. The reasons to move lie elsewhere:
- The legacy connector was built for Seeq R60. It still runs against newer Seeq servers, with warnings, because Seeq has kept its connector interface stable. That stability is a courtesy, not a guarantee, and the legacy connector receives no further development.
- It carries defects that have been worked around rather than fixed: tags with extended characters, reads across a daylight-saving change, and one bad tag stopping an index. See the release notes.
- The current connector is maintained against Seeq's continuous releases. Every new Seeq Connector SDK release is checked and tested before EEI adopts it, and the change is absorbed once, in the shared foundation every EEI connector uses.
What stays the same¶
Your Seeq content keeps working. For a well-formed tag list, the new connector produces the
identical asset tree, signal identities, names and sample values, verified three ways. Worksheets,
analyses, calculations and annotations keep resolving, with no re-index, migration or rework. The one
difference: two signal properties the legacy connector built but never attached, Group Number and
Channel Number, now appear. See
What stays the same.
Your configuration carries over. The new connector reads the same file,
ABB KM Connector V3.json, with the same connection settings. Everything it adds is optional and
defaults to the previous behavior. Because every site's file has its own history, EEI checks your
file with you before the session.
What is new for you¶
| What it means for the upgrade | |
|---|---|
| A license is required | The new connector serves data only with a license issued for its host. Without one it starts but registers no datasources. The legacy connector had no license check. See Licensing |
| Java 21 on the agent host | Check it before the session. It is the one prerequisite that can turn a short session into a rescheduled one |
| Agent version | The agent must be Seeq Link 100.14 or newer. Tell us your Seeq server and agent versions before scheduling |
Files under vforge/ in the agent's data folder |
Reports, configuration backups, the license, the secrets store (secrets/) and vf-agent (bin/, tools/) live there. See what the connector writes |
| New optional settings | Health monitoring in Seeq, request pacing, and certificate validation. All default to the previous behavior |
| Up to 4 Knowledge Manager queries at once | Per connection, the new connector runs up to 4 data queries in parallel; the legacy connector ran at most 2. Data comes back faster, and the connector backs off by itself when Knowledge Manager slows or returns errors. To keep the legacy load on your Knowledge Manager server, set "MaxConcurrentRequests": 2 on the connection. That also limits how many Seeq requests the connection works on at once |
| More complete answers for intermittent signals | Seeq caches what the connector returns, and treats a period with no sample at its edge as "nothing beyond". The new connector looks further for the nearest sample, so trends no longer go blank when you page through history. Expect a few extra, small queries the first time a sparse signal is viewed |
| Credentials move out of the configuration | The Knowledge Manager password is kept in the VForge secrets store on the agent host instead of in the configuration Seeq displays. You move the passwords in the same session, once the upgrade is verified. See Move the credentials |
For your IT team, the one-page summary is For Your IT Team.
How the upgrade runs¶
Why one session¶
The license is bound to the agent host, and the file EEI needs to issue it is written by the new connector when it first starts. A Seeq agent hosts one ABB Knowledge Manager connector, legacy or new. That one connector can serve many datasources: each connection in its configuration is one Knowledge Manager connection, and appears in Seeq as one datasource. So by the time the new connector first starts, the legacy connector has already been removed and set aside, for every datasource on that agent. Finishing the upgrade in the same session, while EEI issues the license, avoids putting the legacy connector back only to remove it again, and keeps the interruption to one.
Who takes part¶
| Who | Role in the session |
|---|---|
| Your IT/OT team | Runs every step on the agent host: stops and starts the Seeq agent, copies files, runs vfa, keeps the rollback copies. Someone with administrator rights on the agent host |
| Someone who knows your Seeq content (recommended) | Confirms at the end that a familiar worksheet still trends |
| EEI | Leads the session, reads the connector log with you, issues your license, and makes the go or roll-back call with you |
| Seeq (optional) | On standby for questions about the agent or the Seeq server. No step needs Seeq to act |
EEI's access to your Seeq server¶
EEI supports its connectors best with an administrator account on your Seeq server: see Access to your Seeq server for what it is for and how it is arranged. For this upgrade it lets EEI gather the Seeq-side information itself, check your datasources during and after the session, and make the Seeq-side changes a rollback needs, with your team watching. Without it, your Seeq administrator joins the session and does those parts, with EEI guiding.
Timeline¶
| When | What |
|---|---|
| About two weeks before | EEI opens a ticket; you run the read-only checks in Before the session and attach the results |
| Before the session | EEI reviews your configuration, prepares your account and license agreement, and posts the release in the ticket |
| The session (plan 90 minutes for a few connections) | The session: rollback copies, the connector swap, the license, Verify, Move the credentials, and the go decision |
| The next scheduled index | The key check after the session: it completes, with the same counts. EEI watches it with you through the ticket |
| One index cycle later | Delete the rollback copies; EEI closes the ticket |
The steps themselves usually take less than 90 minutes. The rest is room for anything unexpected, and for watching the connector: data queries are checked during the session, right after the license is in place.
The commands on this page¶
Every command on this page runs on the agent host, in one of two windows:
| Window | Open it as | Used for |
|---|---|---|
| Windows PowerShell | Start menu → Windows PowerShell → right-click → Run as administrator | Every code block on this page marked powershell, and the vfa commands |
| Seeq Command Prompt | Start menu → All → Seeq Server → Seeq Command Prompt (installed with the Seeq agent). It already runs as administrator; just open it | Only seeq stop and seeq start |
The PowerShell commands are for Windows PowerShell 5.1, which every supported Windows Server has, or
PowerShell 7. They do not run in the ordinary Command Prompt (cmd.exe). Paste them as shown.
One phase or two¶
An upgrade always affects every datasource on the agent being upgraded: they are all served by the agent's one ABB Knowledge Manager connector, so the legacy and the new connector cannot run side by side on it.
Most sites upgrade in one phase: every datasource on the agent in one session. EEI's testing has found no reason to do otherwise.
If you want to validate on one datasource first, choose two phases:
- Phase 1: upgrade an agent that serves a single, representative datasource, and use it normally through at least one index cycle. Datasources on other agents are not affected.
- Phase 2: upgrade the rest, in a second session.
The upgrade preserves item identity by design; phase 1 confirms it at your site, with only that one datasource exposed if anything is wrong. If all your datasources are on one agent today, phase 1 first needs a new agent: provisioning it and moving one datasource, still on the legacy connector, onto it. Weigh that work, and the change it brings of its own, against upgrading every datasource at once. EEI can help you decide.
Your session sheet¶
EEI fills this in from the ticket and sends it with the session invitation. The steps below use these names.
| Name on this page | Means | Your value |
|---|---|---|
<ticket> |
The upgrade ticket at support.endeavoreng.com | |
<agent host> |
The machine that runs the Seeq agent with the ABB Knowledge Manager connector | |
<data folder> |
The agent's data folder | default C:\ProgramData\Seeq\data |
<connector version> |
The release you are moving to, as named in the zip | |
<zip SHA-256> |
The checksum EEI posts with the zip | |
<connections> |
Enabled connections, and so datasources the license must cover | |
<agent account> |
The account the Seeq agent service runs as; the secrets store is readable only by it, SYSTEM and administrators | default NT AUTHORITY\NetworkService |
<rollback folder> |
Where you keep the rollback copies | e.g. C:\eei-rollback\<date> |
Before the session¶
Everything here is done through the upgrade ticket at support.endeavoreng.com: attach results, ask questions, and receive the release there. The checks only read; nothing changes on the agent host.
Prep 1. The ticket (EEI)¶
EEI opens a ticket for your upgrade and adds the people from your side. Everything for the upgrade, including the license, goes through it.
Before 1. Confirm Java 21 or newer¶
The Seeq agent brings its own Java; check that one, not the java on your path. In an Administrator
PowerShell on <agent host>, with the agent running:
Get-CimInstance Win32_Process -Filter "Name='java.exe'" | ForEach-Object { $_.ExecutablePath; & $_.ExecutablePath -version 2>&1 }
Before 2. Send EEI your versions and configuration¶
In the same Administrator PowerShell, run these and attach the output to <ticket>:
Get-CimInstance Win32_Service | Where-Object { $_.Name -like '*seeq*' } | Format-List Name, State, StartName
Get-ChildItem "C:\Program Files\Seeq*" -Recurse -Filter "seeq-link-sdk*.jar" -ErrorAction SilentlyContinue | Select-Object Name
Get-ChildItem "C:\ProgramData\Seeq\data\plugins\connectors" | Select-Object Name
$cfg = Get-Content -Raw "C:\ProgramData\Seeq\data\configuration\link\ABB KM Connector V3.json" | ConvertFrom-Json
$cfg.Version
$cfg.Connections | Select-Object Name, Enabled, WebServiceMethod, WebServicePort | Format-Table -AutoSize
It shows the agent's version (it must be Seeq Link 100.14 or newer), the account the agent runs as,
the installed connectors, and how many connections are enabled (the license must cover them all),
without showing any password. Where EEI has administrator access to your Seeq server, it reads the
Seeq-side facts there; the agent host's facts still come from these commands. If EEI asks for the configuration file itself, remove the passwords
before attaching it.
A connection with https on port 80 will not connect: https uses port 443 unless your
Knowledge Manager server says otherwise. EEI will point it out; fix it before the session and confirm
that the legacy connector still connects.
Prep 2. Your account and license agreement (EEI)¶
EEI sets up your account and the license agreement behind it: the product, how many datasources it covers, and until when. Send what EEI asks for in the ticket before the session and this is ready when you join (recommended). It can also be done live at the start of the session, which adds about 15 minutes.
Prep 3. The release (EEI)¶
EEI posts the release zip, vforge-seeq-link-connector-abbkm-<connector version>.zip, and its
<zip SHA-256> in the ticket. Copy it to <agent host> before the session (not into the Seeq folders)
and check it in PowerShell, in the folder where you saved it:
Get-FileHash .\vforge-seeq-link-connector-abbkm-<connector version>.zip -Algorithm SHA256
The hash must match <zip SHA-256>.
Before 3. Schedule the session¶
Agree a time when a short interruption of the ABB Knowledge Manager datasources is acceptable, and who joins (see Who takes part).
The session¶
Open an Administrator PowerShell and the Seeq Command Prompt on
<agent host>. EEI reads the connector log with you after each start; it is
<data folder>\log\jvm-link\jvm-link.log.
| Step | Action | You should see |
|---|---|---|
| Window 1. Stop the agent | In the Seeq Command Prompt: seeq stop |
Success: No Seeq-related ports appear to still be in use. The service interruption starts here |
| Window 2. Set aside the legacy connector | Copy the configuration file to <rollback folder>, and move the legacy connector's folder abb-km-seeq-link-connector-4.5.2-… there from <data folder>\plugins\connectors (cut and paste, or the commands below) |
Both in <rollback folder>; the other folders in connectors stay |
| Window 3. Place the new connector | From the zip, copy only the folder vforge-seeq-link-connector-abbkm-<connector version> into the same connectors folder. Leave the configuration as it is: the new connector reads it unchanged |
It contains a .jar file and lib and bin folders |
| Window 4. Start, unlicensed | seeq start. The connector starts unlicensed: it keeps your configuration and your Seeq content, copies each Knowledge Manager password into the secrets store, and serves no data yet |
EEI confirms the right version loaded and the passwords are in the store. Seeq lists your datasources, disconnected |
| Window 5. Send the license request | Attach <data folder>\vforge\products\seeq-connector-abbkm\license-request.json to <ticket>. It names the product, the connector version, your host and how many connections need a license, and holds no password |
|
| Window 6. EEI issues your license | EEI checks the request against your license agreement, issues a license bound to this host, checks it, and attaches the .lic file to the ticket. A few minutes |
A .lic file in the ticket |
| Window 7. Place the license | Save the .lic file, under the name EEI gave it, in that same seeq-connector-abbkm folder. The connector picks it up within a minute, with no restart |
EEI sees license state=LICENSED; your datasources connect |
The Window 2 commands, in the Administrator PowerShell, with the agent stopped:
$rb = "C:\eei-rollback\" + (Get-Date -Format "yyyyMMdd-HHmm")
New-Item -ItemType Directory -Force $rb | Out-Null
Copy-Item "C:\ProgramData\Seeq\data\configuration\link\ABB KM Connector V3.json" $rb
Move-Item "C:\ProgramData\Seeq\data\plugins\connectors\abb-km-seeq-link-connector-4.5.2*" $rb
Get-ChildItem $rb | Select-Object FullName
The configuration copy holds your Knowledge Manager password, and once the credentials have moved it is the only copy that does: the new connector's own configuration backups hide passwords. Store it as carefully as the password itself.
Saving the license: make sure the file ends in .lic. Some editors and browsers save it as
….lic.txt, which the connector does not read. Get-ChildItem the folder to check.
Verify¶
| Check | Expected |
|---|---|
| Seeq, Administration → Datasources | Each datasource is present, connected, and shows <connector version> |
| Connector log | license state=LICENSED, not UNLICENSED, EXPIRED or HOST_MISMATCH. "The connector started" does not mean it is licensed |
| Index | Request Index on each datasource. The index completes, with item counts and no repeated write errors |
| Item count | About the same number of signals as before the upgrade. A large drop means tags are being skipped: tell EEI |
| Existing content | An existing worksheet or analysis still shows its signals. This is the continuity check that matters most |
| Workbench | A known tag returns data over a known period, including one that spans a daylight-saving change if you have one |
Move the credentials to the secrets store¶
Done in the same session, once Verify passes. At its first start (Window 4) the new connector copied each
password from the configuration into the secrets store (vforge\secrets\credentials.json in the agent's
data folder), readable only by the agent's account, SYSTEM and administrators, and logged a warning that
passwords in the configuration are deprecated. The passwords are still in the configuration too. The
connector also installs vf-agent in vforge\bin\. The
steps below then take the passwords out of the configuration. They work the same for one connection or
many.
Point a short command at vf-agent in the Administrator PowerShell:
$vf = "<data folder>\vforge\bin\vf-agent.cmd"
function vfa { & $vf @args }
vfa secrets verify
If you prefer the ordinary Command Prompt (cmd.exe) for vfa, this is the equivalent; the rest of this page assumes PowerShell:
set "VF=<data folder>\vforge\bin\vf-agent.cmd"
doskey vfa="%VF%" $*
vfa secrets verify
The steps below use vfa. See vf-agent for
more.
Linux agents. Seeq currently supports the Seeq agent on Windows. Linux instructions are kept here, and kept up to date, for when Seeq supports Linux agents again. On Linux, run
<data folder>/vforge/bin/vf-agentas the account that runs the Seeq agent.
| Step | Action | You should see |
|---|---|---|
| Credentials 1. Check the store is restricted | vfa secrets protect. If it asks for --account, give <agent account>, for example vfa secrets protect --account NetworkService. On Linux the connector already creates it readable by its owner only |
Every row PASS: the store is readable only by the agent's account, SYSTEM and administrators |
| Credentials 2. Preview | vfa secrets migrate --product seeq-connector-abbkm --all. Nothing is written |
Every connection replace (copied at Window 4) or harvest+replace. A blocked row says what is missing; nothing moves until it is resolved |
| Credentials 3. Apply | seeq stop (Seeq Command Prompt), then the command below in PowerShell, on its own (it asks a question, and a pasted block would answer it with the next line). Type yes |
Output opening with Migration applied: and the number of connections moved |
| Credentials 4. Start and check | seeq start (Seeq Command Prompt), then vfa secrets verify --require-store (PowerShell) |
Every row PASS; each connection connects; Seeq, Administration → Datasources → the connector's configuration shows VFORGE_SECRETS in place of each password |
The Credentials 3 command:
vfa secrets migrate --product seeq-connector-abbkm --all --apply --agent-stopped
It shows how many connections it will move and asks you to type yes; anything else changes nothing. In
a script, add --yes. It then confirms every connection's credential is in the store, writes a masked
backup of the configuration, replaces each connection's UserName, Password and Domain with
VFORGE_SECRETS, and checks the result. If anything is missing it changes nothing.
The checks after config-rewritten are secrets verify, run afterwards: a FAIL there, such as a
permissions finding, does not undo the migration. Fix what it reports, and if an account has access to
the store on purpose (a backup or monitoring account, for example), name it with
--allow-access <account>, which verify then accepts and lists in its result.
To move one connection at a time instead, replace --all with --datasource <connection Id>, repeated
as needed. Connections not named are left as they are.
The go decision¶
Before the session ends, you and EEI confirm together:
license state=LICENSED, and every enabled connection registered;- every connection connected, and Request Index completed with about the same counts as before;
- an existing worksheet trends;
vfa secrets verify --require-storeall PASS.
If any of these fails and cannot be fixed in the session, roll back the same day (below) and keep the connector log and both configuration files for EEI. Rolling back is a planned option, not a failure.
Rolling back¶
Stop the agent (seeq stop), remove the new connector folder, put back the legacy folder and your
configuration copy from <rollback folder>, and start the agent (seeq start). The legacy connector does
no license check, so rollback needs no license action. Because item identities are the same in both
directions, rolling back does not orphan Seeq content.
The legacy connector reads the password only from the configuration. After the credentials have been moved, rolling back therefore needs the copy of the configuration you kept in Window 2, which still holds the passwords.
Seeq keeps its own copy of each datasource's settings, and it wins. In Seeq, Administration →
Datasources → the datasource → Configure, the Additional configuration box holds the connector's
settings for that connection. When the agent starts, Seeq writes those values into the agent's
configuration file. After the credentials have moved, that copy reads VFORGE_SECRETS, so a restored file
alone is overwritten and the legacy connector cannot log in. After Credentials 3, roll back in this order:
seeq stop; put back the legacy folder and your configuration copy, and remove the new connector folder.- For each ABB Knowledge Manager datasource, in Configure → Additional configuration, replace the
content with that connection's settings from your configuration copy, including
UserName,PasswordandDomain, and select Update. Entering{}does not clear Seeq's copy: enter the values. A Seeq administrator does this; EEI can, where it has administrator access to your Seeq server, with your team entering the passwords. seeq start, and check that each datasource connects.
Before Credentials 3, Seeq's copy still holds your passwords, and step 2 is not needed.
The legacy connector ignores the vforge folder in the agent's data folder. After a rollback that folder
still holds the secrets store, with your Knowledge Manager passwords. Keep it if you plan to retry the
upgrade (the license in it stays valid for this host); otherwise delete it, or ask EEI.
Keep the rollback copies for at least one full index cycle after the upgrade, then delete them and tell EEI in the ticket.
After the upgrade¶
Later releases are routine: EEI tracks Seeq's releases, tests against them, and delivers updates on a schedule agreed with you. Each release is described in the release notes.