Manage relays
- Synopsis
- Full Details
In briefA relay is the software you install on your own network so that legacy LSAM machines,
and OpCon MFT, OpCon RPA and EASE agents, can run jobs Continuum dispatches from the cloud. It
connects outbound only and authenticates with a credentials.json file. You download it and
register it on Agents › Relays, install it on a Linux or Windows host, and then register the
agents behind it on the Agents tab.
- Download Relay creates nothing and issues no credential, so you can fetch the software first.
- The installers take the connection details as arguments; re-running one to upgrade or change a setting keeps every option you don't pass.
- A newly registered relay reads Offline until it is installed and first checks in.
- The Relays tab and each of its actions need their Relays permission.
GET http://localhost:8080/healthreturns 200 once the relay is ready and 503 while it starts.- A relay started twice serves from one process; the other waits as a standby and takes over if the first stops. The Relays tab badges a relay running as more than one process, and shows No Standby on an online relay running as one.
- Hand Over, in Edit Relay, moves a relay to a ready standby before planned maintenance. It needs Relays Edit and cannot be cancelled once it starts.
- A clean stop shows in about a second and raises an Agent Offline for each of its legacy agents; an abrupt loss takes about two minutes, and the agents read Unknown, then Offline if the relay is still gone after an hour.
- The Client Secret is shown once. If it is lost, rotate the credentials rather than re-registering.
- Deleting a relay that still has jobs ends them: they fail and are not retried. Stop the relay and wait a minute first.
- A legacy agent with no Default event environment loses every event its machine raises.
- An out-of-date relay can fail or quietly drop newer features; upgrade it with each platform release, and check its Version on the Relays tab afterwards.
- On Windows, let the installer stop and restart the relay during an upgrade; a relay you stopped first stays stopped.
A relay lets your on-prem legacy LSAM machines run jobs that OpCon Continuum dispatches from the cloud. You install it on your side, it connects outbound to OpCon (no inbound firewall changes), and it hands work to the LSAM machines behind it.
Your legacy LSAM machines live on-prem, but the scheduler runs in the cloud, and opening inbound firewall holes to reach them is a non-starter. The relay bridges that gap with a single outbound connection, so cloud-scheduled work reaches on-prem machines without exposing them.
How a relay connects
- It connects outbound only: nothing inbound needs to be opened to the internet.
- It authenticates with a
credentials.jsonfile — the client ID and secret you're shown once when you register it. - One relay can front several legacy agents, and a legacy agent group can span more than one relay.
- Set Up
- Credentials and Security
- Rename, Delete or Stop
- Logs
- Updates
- Troubleshooting
Set Up
Set up a relay in this order. Each step has its own section below.
- Get the relay software.
- Register the relay, and store its credentials.
- Install the relay on a Linux or Windows host.
- Confirm it's running.
- Give each legacy agent a default event environment.
Get the relay software
On Agents › Relays, choose Download Relay, beside New Relay in the toolbar. The dialog names the latest published version and its publish date, and offers a download button for each platform that release covers.
This creates no relay and issues no credential, so it is safe to do before you have decided anything.
Earlier builds offered the artifact only on the relay registration success screen, so getting the binary meant registering a relay — and because reopening that dialog resets it, a download that failed left you registering a second relay to try again. If a runbook of yours says to register in order to download, it can be simplified.
If Download Relay is greyed out, hover it: the tooltip distinguishes a lookup still in progress, no release available, a release that covers no platform offered here, and a lookup that actually failed. The last one is worth chasing; the others are not faults.
Register the relay
To register a relay, complete the following steps:
- Go to Agents › Relays and choose New Relay.
- Enter a Name — letters, numbers, dashes, underscores and dots — and the Host Name of the machine it runs on, then choose Save.
- On the credentials screen, store the credential before anything else: choose Download credentials.json — the file the relay needs to authenticate — which also ticks I have stored this secret for you. If you copy the Client ID and Client Secret instead, tick I have stored this secret yourself.
- Note the connection details shown: the
AGENT_SERVICE_URLand path prefix for your environment. Each has a copy button, and the installer takes them as arguments. - Copy the Run the relay commands for your platform. They are pre-filled with this environment's URL and the release's version.
- Choose Done.
The new relay is listed as Offline, with a Last Heartbeat of Never, until you have installed and started it. That is expected: it turns Online when it first checks in.
Once you close the dialog, the Client Secret is gone — closing before you tick I have stored this secret asks you to confirm first. If you lose it you do not need to start over: rotate the credentials instead, on the Credentials and Security tab.
The artifact on its own cannot connect: the installer needs your environment's connection details,
and the relay cannot authenticate without credentials.json. Registering gives you both.
Install the relay
Both platforms follow the same three moves: extract, install, then replace the placeholder
credentials and start the service. A first install does not start the relay, and it places a
placeholder credentials.json that the relay cannot authenticate with.
- Linux (systemd)
- Windows
cd ~/Downloads
tar -xzf opcon-relay-<version>-linux-x64.tar.gz
cd opcon-relay-<version>
sudo ./install/install.sh --agent-service-url <url>
sudo cp /path/to/credentials.json /etc/opcon/credentials.json
sudo systemctl enable --now opcon-relay
The installer puts the app under /opt/opcon-relay, writes your settings to /etc/opcon/relay.env,
and logs to /var/log/opcon-relay. To change a setting later, edit relay.env and
sudo systemctl restart opcon-relay, or re-run the installer with just that option.
It also gives the service a state directory at /var/lib/opcon-relay, which is where the relay
keeps what it needs to resume after a restart. /etc/opcon stays read-only, which is the point:
earlier Linux relays kept that state in the config directory and so could never write it, and a
restart lost track of the legacy jobs that were running and did not recover OpCon MFT or OpCon RPA
runs in flight. If you are running a Linux relay from an earlier build, re-run the installer —
there is nothing of your own to configure. A relay stopped part-way through writing that state now
comes back with it intact, on every platform: the files are written to a temporary sibling and
renamed into place, so a restart never reads a half-written one. See
Surviving a relay restart.
In PowerShell, as Administrator:
cd $HOME\Downloads
Expand-Archive .\opcon-relay-<version>-windows-x64.zip -DestinationPath .
cd .\opcon-relay-<version>
powershell -ExecutionPolicy Bypass -File .\install\install.ps1 -AgentServiceUrl "<url>"
Copy-Item C:\path\to\credentials.json C:\ProgramData\OpCon\Relay\credentials.json -Force
Start-Service OpConRelay
The installer puts the app under C:\Program Files\OpCon\Relay, its config and credentials under
C:\ProgramData\OpCon\Relay, the relay's own logs under C:\ProgramData\OpCon\Relay\logs, and
the LSAM Connector's under C:\ProgramData\OpCon\Relay\dotnet. The -ExecutionPolicy Bypass is
needed because a downloaded script is blocked by the default policy.
Both log folders must hold nothing but relay logs — the installer aborts on a drive root, a
junction, or a folder with anything else in it, because SYSTEM creates and deletes files there. If
you override them with -LogDir or -ConnectorLogDir, give each its own empty folder.
Before it changes anything, the installer also refuses a relay folder, a parent folder or a file
in them that a non-administrator owns or can change, or that is a junction or link, and a folder
that overlaps the install folder. An overlapping folder or a drive root is refused with a message
starting Invalid, naming the folder. For an item that is a link, or that a non-administrator owns
or controls, the message starts Refusing to install:, names the item, and says how to fix it;
unless it says otherwise, nothing was changed. If you choose your own
-InstallDir, restrict it to Administrators and SYSTEM yourself. See
What the installer checks.
One relay runs on a host at a time. You can install a second relay on the same host with its
own -ServiceName and folders, and it is displayed as OpCon LSAM Relay (<name>), but both use
the same ports, so stop one before you start the other. See
More than one relay on a host.
The installer sets them on the service itself, and the service's own environment wins.
Copy your credentials.json onto the placeholder rather than deleting and replacing it — that
keeps the restricted ownership and permissions the installer applied.
The installers take the connection details as arguments, so you do not set environment variables
by hand. Use the values from the register dialog: --agent-service-url / -AgentServiceUrl is
required on a first install — both installers stop without it, before changing anything — and
the path prefix (for example /agent-api) is for cloud environments — leave it empty for local or
dedicated setups.
No runtimes to install. The Linux and Windows packages are self-contained and bundle everything
the relay needs, so you do not need Node.js or .NET on the host. A Linux host must be 64-bit x86
(x86-64) with glibc 2.28 or later — RHEL 8, Ubuntu 20.04, Debian 11 or newer — and have the ICU
(libicu) and OpenSSL 1.1.1 or later (libssl) libraries, systemd, and root (sudo). Every download also contains a
README.md with the full numbered steps and parameter tables for that release.
Confirm it's running
On any platform, GET http://localhost:8080/health returns 200 once the relay is ready, and
503 while it's still starting. On the Relays tab, the relay turns Online with a recent
Last Heartbeat, and its legacy agents come online.
A second copy of a relay waits as a standby. If the same credentials.json is started in a
second place, the second process waits as a standby: it takes no work and connects to no agent, its /health reads
{"status":"standby"}, and it takes over by itself, without a restart, if the first one stops —
within seconds of a clean stop, or about 40 seconds after a crash. While it is ready, a stop or a
crash of the active process raises no offline notifications and holds no work, and the standby takes over the legacy jobs and the OpCon MFT, OpCon RPA and EASE runs that were in flight, without sending any of them again; one whose result it cannot confirm shows as Lost in Failover. After the active host vanishes, rather than crashes, check a Lost in Failover job on its machine before you run it again: it may still have run. The Relays tab shows
an instances badge, such as 2 instances, on a relay running as more than one process, and Edit
Relay lists each one with its host, version and role. An Online relay running as one process
shows No Standby instead: if that process stops, jobs on its agents cannot start until it
restarts. To keep a relay running through a stop or a host failure, start a second copy on another
host with the same credentials.json; if a second copy is one you did not mean to run, stop it. See
More than one relay process.
Expect all of them, however many you have assigned. Earlier builds handed the relay only the first 50 agents by name, so on a larger relay the agents late in the alphabet never came online and jobs on them could not return their output. If that is what you have been seeing, this release is the fix — there is nothing to reconfigure, and no reason to split the relay in two.
To check the service itself:
- Linux (systemd)
- Windows
systemctl status opcon-relay shows the service, and journalctl -u opcon-relay shows its logs.
The LSAM Connector also writes lsam-connector-<date>.log into /var/log/opcon-relay, cleaned up
for you — see Logs, rotation and retention.
Earlier Linux relays could not write that file at all; its output went only to the journal.
Get-Service OpConRelay shows the service. Its logs are relay-stdout.log and relay-stderr.log
in C:\ProgramData\OpCon\Relay\logs; the LSAM Connector's are lsam-connector-<date>.log in
C:\ProgramData\OpCon\Relay\dotnet. Both are cleaned up for you — see
Logs, rotation and retention.
Give each legacy agent a default event environment
Machines behind a relay can raise Continuum events themselves — a job or process writes a file of event syntax into the agent's MSGIN directory and the agent sends it up the connection it already holds. Every legacy agent needs one thing set before that works: a Default event environment, on its New Agent or Edit Agent dialog on the Agents tab.
Registration requires it, for every legacy LSAM type and for EASE, and what you enter is checked against your tenant's environments as you save — so you cannot register one of these agents into a state where its events go nowhere. OpCon MFT and OpCon RPA agents have no MSGIN directory and are not asked for one.
An unset Default event environment refuses every event the machine raises, and the machine deletes the event file before the platform sees it, so nothing appears in the event log to tell you. That state is still reachable: editing an agent can clear the field, and an agent registered before the field became required may never have had one. While any exist, the Agents tab warns you and offers one action, Assign environment…, to assign an environment to all of them. See Events raised by a legacy agent.
Every line a machine raises ends with a login ID and a token, and Continuum now verifies that pair — a line whose credential fails is rejected and never becomes an event. A token carried over from a legacy OpCon server is not one it recognises.
For each emitter, create an event identity named for the login ID the file already uses, on Administration › Permissions › Event Identities, and put its secret where the old token was. The file format, the scripts and the login ID all stay as they are. Grant the identity only the roles it needs — copying an administrator login is how a full-admin token ends up on every machine. See the credential pair.
Credentials and Security
Rotate credentials
If the client secret is lost or you want to cycle it, rotate the credentials instead of deleting and re-registering the relay. To rotate them, complete the following steps:
-
On the Relays tab, open the relay's row menu and choose Rotate Credentials.
-
Type the relay's name to confirm, then choose Rotate. The current credentials stop working immediately, and the relay stays offline until you finish the next steps.
-
Store the new credential the same way as when you registered it: choose Download credentials.json, which ticks I have stored this secret, or copy the Client ID and Client Secret and tick it yourself. Then choose Done. You can't see the secret again; if you lose it, rotate again.
-
Replace the file on the relay host and restart the service:
Platform Replace Then Linux /etc/opcon/credentials.jsonsudo systemctl restart opcon-relayWindows C:\ProgramData\OpCon\Relay\credentials.jsonRestart-Service OpConRelay
Keep it secure
- Protect
credentials.jsonwith restrictive permissions (the installers do this for you, so keep them if you replace the file manually). - The relay needs no inbound internet ports. Port
8080(/health) is only for local health checks. - Treat the client secret like a password: never share or commit it.
- To encrypt the relay's connection to a legacy agent, turn on the agent's Use TLS for Scheduling (relay 1.24.0 or later). A certificate from an authority the relay's host trusts needs nothing more; for your own authority or a client certificate, set the relay's scheduling TLS variables, and keep the client key readable only by the relay's account.
- On Windows, leave the log folders to the installer. It restricts both to Administrators and SYSTEM (Users: read) and refuses a folder anyone else could plant files in, because the service and the retention task write and delete there as SYSTEM.
Rename, Delete or Stop
Rename or delete a relay
Select a relay to open Edit Relay, where you can change its Name and Host Name. Nothing changes on the relay host, so there's nothing to restart. A relay's old name stays reserved after a rename, so a new relay can't be registered with it.
To delete a relay, use its row menu. A relay with agents can't be deleted — delete its legacy agents on the Agents tab first. An agent can be deleted only once it is offline or Marked Offline and nothing uses it; see An agent in use cannot be deleted. Deleting a relay revokes its credentials.
A relay that still has jobs is not deleted straight away. If you are retiring it for good:
- Stop the relay on its host, and wait one minute after it shows Offline on the Relays tab.
- Choose Delete on its row. Delete Relay and End Jobs says how many jobs it still holds, not started and started.
- Choose OK to delete the relay and end those jobs, or Cancel to keep both.
The ended jobs fail — one that had started reports Relay deleted before the job finished — and none is retried. Rerun any you still need on an agent behind another relay. Ending the jobs needs Agents Delete as well as Relays Delete. To keep the jobs instead, let them finish or kill them, then delete the relay. See Edit, rename and delete a relay.
Hand over to a standby
Before you patch or reboot the host of a relay's active process, move the relay to its standby, so the relay keeps serving its agents throughout. You need Relays Edit.
- On the Relays tab, select the relay to open Edit Relay.
- In the Instances section, choose Hand Over on the row of the standby that should take over. Only a standby that is ready — a current relay build that has checked in within the last 30 seconds — has the button.
- In Hand Over Relay, choose Hand Over. Once it starts, the handover cannot be cancelled.
- If Hand Over Anyway appears, the standby runs an older relay version than the active process, or a version is not known, and handing over can undo an upgrade. Choose Hand Over only if that is what you mean; otherwise choose Cancel and upgrade the standby first.
Verify: the section shows each step under its heading, and The standby on <host> is now
active. when it is done. The relay and its legacy agents stay Online, and running jobs carry on.
The previous active process restarts as a standby by itself; a relay run as a container needs a
restart policy such as --restart on-failure for that. Then work on its host.
If Hand Over is unavailable with The active instance cannot hand over. Upgrade it, or stop it to let a standby take over., the active process runs a relay build that cannot hand over: stop it cleanly instead, and the standby takes over within seconds. If the section reads The handover did not complete. Check the instances below, then try again., check that the standby is still running and try again. See Hand over to a standby for every message.
Stopping a relay
Stop the relay cleanly — sudo systemctl stop opcon-relay or Stop-Service OpConRelay —
whenever you have the choice. A clean stop is reflected in OpCon in about a second, and it leaves the
relay's legacy agents Offline, which holds queued legacy-group jobs in Waiting: Machine until the
relay comes back. The stop command itself can take up to about 35 seconds while the relay finishes
its shutdown — see How long a stop takes.
Expect notifications for the agents, not just the relay. A clean stop of a relay with no standby raises an Agent Offline event for each legacy agent it takes down, alongside the Relay Offline for the relay itself — so anyone subscribed to agent connectivity hears about a planned restart. That is the point: the relay's heartbeat raises an Agent Online for each of them on the way back up, and until recently there was no matching Offline, which made every planned restart look like a run of unexplained outages. If a maintenance window should be quiet, silence the triggers rather than skipping the clean stop.
If the relay disappears without warning instead — killed, power lost, network dropped — it takes about two minutes of missed check-ins to be noticed, and its legacy agents go Unknown. Queued legacy jobs hold through that too, whether they are aimed at a group or at one of those agents, and resume when the relay reconnects. If the relay is still gone after an hour, its Unknown agents go Offline, and when it returns, each agent that is still down raises one Agent Offline. The two-minute window is deliberate: a shorter one would put every queued legacy job on that relay through a hold for a brief network blip.
For planned maintenance, stopping the service cleanly gets you the honest status in about a second instead of two minutes. On earlier builds it was worth more than that — an abrupt loss used to fail the group's queued jobs rather than holding them — so if you have read that advice before, the reason for it has changed even though the advice hasn't.
Logs
Log housekeeping on Windows
You do not have to prune relay logs by hand. The installer registers a daily scheduled task,
\OpCon\OpConRelay-LogRetention (03:00, SYSTEM), which rotates the relay's logs and deletes
rotated ones older than -LogRetentionDays — 30 days unless you pass something else. The
active relay-stdout.log and relay-stderr.log are never deleted, and the LSAM Connector keeps
its own newest 10 daily files.
Two things to watch:
- To change the retention period, re-run the installer with just
-LogRetentionDays. A re-run without it keeps the current period. - If rotated logs pile up anyway, look at the task's Last Run Result. A non-zero result means it refused to prune — usually because the log folder is a junction or is no longer owned by Administrators or SYSTEM.
Uninstalling removes the task and deletes only the relay's own log files; a folder holding
anything else is left in place, and -KeepLogs keeps both folders as they are. Without
-KeepConfig, it also deletes credentials.json and the relay's state files, and removes
C:\ProgramData\OpCon\Relay once nothing is left in it. See
Logs, rotation and retention and
Uninstalling a Windows relay.
Updates
Upgrade the relay or change a setting
Re-run the installer from the new package's extracted folder. A re-run keeps the existing
settings: every option you leave out keeps its current value, so pass an option only to change it.
Your own additions are kept too — lines you added to relay.env on Linux, and entries you added with
nssm edit on Windows. The installer prints each value with where it came from.
- Linux (systemd)
- Windows
Stop the relay, re-run the installer, then start it again:
sudo systemctl stop opcon-relay
cd /path/to/opcon-relay-<new-version>
sudo ./install/install.sh
sudo systemctl start opcon-relay
A relay.env line for a variable the service unit sets itself — CREDENTIALS_FILE, for example —
is dropped with a warning naming it. Pass the matching option, such as --config-dir, instead.
In PowerShell as Administrator, from the new package's extracted folder, re-run the installer and leave the service alone:
powershell -ExecutionPolicy Bypass -File .\install\install.ps1
The installer checks the package and every folder first, copies the new files in beside the old ones, stops the relay, swaps the files over, and starts the relay again if it was running. A relay you stopped first stays stopped. The stop can take up to about 35 seconds, and PowerShell repeats Waiting for service … to stop until it finishes — that is expected. If the upgrade fails after the stop, the installer starts the relay again when that is safe and says so. Do not interrupt it: if you press Ctrl+C or close the window mid-upgrade, re-run the installer before you start the relay.
- A relay with its own
-ServiceNameneeds that-ServiceNameon every re-run. - The first upgrade from an earlier package still stops the relay with that package's short limit, about 3 seconds, so do it while no jobs are running. Later upgrades get the full time.
- To go back to an earlier package, run
Stop-Service OpConRelayfirst, then start it yourself after the install. - To restart the relay, use
Restart-Service OpConRelay, nevernssm restart, which leaves it stopped.
If a re-run cannot use a setting it finds on the existing install, it refuses and names the option to pass; nothing is changed. See Re-running the installer and Upgrading a Windows relay.
Keep the relay up to date
A relay runs on your infrastructure and isn't upgraded for you, so it can fall behind the platform. These things depend on it being current, and each looks like a product fault rather than a version gap:
- Output files from UNIX and IBM i agents. An older relay asks for them the way only a Windows agent expects. On UNIX the agent answers with its own global log files; the platform now discards those before storing the listing, so the job's output comes back empty rather than wrong. On IBM i nothing comes back.
- The newer IBM i job types. An older relay builds every IBM i job as a batch job, so IBM i - Operator Replay, Restricted Mode, FTP and File Arrival jobs fail loudly on it. An IBM i job's message monitor, spool-file and dynamic-variable lists are covered by the next item: a relay that has not reported it can send them is refused the job.
- An IBM i job's message ID. A current relay passes on the message ID an IBM i agent reports
when a job ends — for example
SMA0036orSMA0037— as the job's Exit Description. An older one does not, so the job's Termination stays blank on success and an Exit Description event has nothing to compare. - The Oracle, Other DB and MySQL SQL job types. An older relay refuses their dispatch as an unsupported job type, so the job never starts.
- The SAP R/3 Job, SAP BW Process Chain, z/OS Batch Job, MCP and OS 2200 Job types. An older relay has not reported that it can run SAP R/3 and CRM, SAP BW, z/OS, MCP or OS 2200 jobs, so their dispatch is refused with RELAY_LSAM_PLATFORM_UNSUPPORTED and the job never starts.
- Settings an older relay would drop. A job with IBM i message monitors, spool files or dynamic variables, an MCP prerun, z/OS step control, pre-runs or restart options, an OS 2200 prerun, file dependencies or the XML job start format, or a Windows Command Process Priority other than Normal is refused at dispatch by a relay that has not reported it can send them — any relay older than this release — and goes to Initialization Error with RELAY_LSAM_FEATURE_UNSUPPORTED, naming the relay. Upgrade the relays before Builders use them. A legacy agent group prefers a member whose relay can send the job's settings.
- The z/OS Started Task, z/OS REXX Exec and z/OS Console Command types. A relay that already runs z/OS Batch Jobs but predates these types fails them at dispatch with Unsupported z/OS task type for TX1 translation, and nothing reaches the agent.
- Restarting a z/OS job on a step, and z/OS JCL access. A relay that predates them refuses a z/OS job restarted on a step — the job does not run, rather than running from the beginning — and the JCL dialog says The relay serving this agent is too old for JCL access. See Restarting it and Viewing and editing JCL.
- Restarting a job on a step. An older relay collects no steps, so the Restart dialog offers none, and a job restarted on a step goes to Initialization Error with RELAY_LSAM_FEATURE_UNSUPPORTED rather than running from the beginning. See Restart on a step.
- Agent feedback and output while a job runs. An older relay passes on none of a legacy job's agent feedback, so its Agent Feedback section stays empty and LSAM Feedback events never fire, and it lets the Output tab list a job's files only once the job has ended. Both are quiet.
- Non-ASCII characters in job output. An older relay reads a legacy job's output files as plain
ASCII, so every accented or other non-ASCII character shows as
?on the Output tab. This one is quiet. - IBM i values as typed. An older relay converts quotes, ampersands and angle brackets in an IBM i job's values to XML entities, so a quoted value in a Call reaches the machine as entity text.
- Advanced exit criteria. A Builder who sets Exit Criteria Result, a range condition, or more than five conditions on a legacy job will find the job's dispatch refused on an older relay. It fails loudly rather than guessing, but the job doesn't run. A UNIX - Episys: Run JobFile or UNIX - Episys: Find Report from RSJ Output table is the exception: Continuum always evaluates it, so it works on any relay build.
- IBM i job submission. An older relay sends a job name holding a character an IBM i job name can't contain, so the agent refuses the submission and the job ends immediately in Initialization Error.
- Windows - File Arrival file names in double quotes. An older relay refuses the dispatch on any double quote in the file name, so the job never starts.
- A legacy job's schedule date. An older relay sends its own UTC date instead of the workflow's schedule date. West of UTC an evening dispatch carries tomorrow's date, so a File Arrival window watches the wrong day. This one is quiet.
- Per-agent Check CRC and XML escaping. Behind an older relay, saving a changed Check CRC on a legacy agent is refused, and a Windows, SQL or MCP agent whose Requires XML Escape Sequences differs from its default has its jobs refused with RELAY_LSAM_FEATURE_UNSUPPORTED. See Check CRC and Requires XML Escape Sequences.
- Mark Offline stopping communication. An older relay keeps a Marked Offline agent's connection open. New work is still held, but the agent's status warns Communication is not stopped. Upgrade the relay to stop communication with this agent. Every running instance of the relay must be current. See What Mark Offline does to communication.
- Detecting an agent that stops answering without disconnecting. An older relay waits for its send retries to give up — about two and a half hours at the default response timeout — while the agent's running jobs sit in Running and the agent still reads as reachable.
- OpCon MFT, OpCon RPA and EASE agents. Each relay reports, on every check-in, whether it can serve each of these three REST-reached agent types — on separate flags, so a relay able to serve one is not thereby able to serve another. Registering an agent of a type the relay has not reported is refused in the dialog (Failed to create agent. Upgrade the relay to register MFT agents., Failed to create agent. This relay must be upgraded to run OpCon RPA agents. or Failed to create agent. This relay must be upgraded to run EASE agents.; editing an RPA or EASE agent there starts Failed to update agent. instead), an already-registered agent of that type behind a fallen-behind relay is never given work, and an OpCon MFT, OpCon RPA or EASE job whose agent pool is served by that relay is refused rather than queued. A least-tasked legacy agent group member or a backup agent on such a relay is skipped for those jobs. This one at least says so plainly — see Relays and Serving EASE agents.
Nothing in the platform can tell an out-of-date relay from a job with no output, so when legacy
behaviour goes wrong on only some platforms, check the relay build first. The Version column on
the Relays tab shows the build each relay reported when it last checked in, and Download
Relay names the latest published version and serves it, so you can compare the two without
touching your relay registrations. A relay that checks in but shows — runs a build from before
relays reported their version, so upgrade it. After an upgrade, the new version shows at the
relay's next check-in.
A legacy job's output files are named by the relay when the job is dispatched, and the request that lists them is built by the platform when someone views them. Both sides apply the same naming rule, and that rule changed on both at once — so a mismatch in either direction stops new jobs' output from being found. There is no safe side to be on: plan the relay upgrade alongside the platform release rather than after it.
Two things to tell your Operators about jobs that ran before the upgrade:
- Their output files keep their old names on the agent permanently. Output someone already viewed stays available; output nobody viewed comes back empty, and no upgrade order fixes that.
- Refresh from agent on one of those jobs re-reads from the agent, so it replaces an old stored listing with an empty one. That's deliberate — a listing the platform can't vouch for is dropped rather than kept.
Running jobs is unaffected. This is only about retrieving their output.
Once the relay is current it reports the exact name it sent with each job's completion, and the platform uses that name to find the job's output — so for jobs it dispatches, the two sides can no longer disagree.
Files whose names don't belong to the requesting job are discarded. Before this, a request a UNIX agent didn't recognise came back with the agent's own global log and error files, which were stored and served as that job's output — so an Operator could read another job's output believing it was their own. The platform repeats the check before it stores a listing, so even an older relay can't get the global log stored as a job's output. The check applies to UNIX listings; Windows and IBM i listings aren't filtered, because their file names carry no job-name prefix to match on.
Troubleshooting
When something's wrong
| Symptom | Likely cause | Fix |
|---|---|---|
| A UNIX or IBM i job's output files are empty or hold the agent's own logs | The relay predates per-platform output requests | Upgrade the relay, then have the Operator use Refresh from agent on the affected jobs. |
| A legacy job never starts, refused on its exit criteria | The relay predates Exit Criteria Result, range conditions, or tables over five rows | Upgrade the relay, or have the Builder use up to five plain conditions with Exit Criteria Result Fail. |
| A UNIX or IBM i job that ran before a relay upgrade lists no output files | Its files were written under the old naming rule | Expected and not repairable — the names on the agent don't change. Output viewed before the upgrade is still stored. Re-run the job for output under the current rule. |
| An IBM i job fails at once with Initialization Error, and the agent reports a submission failure | The relay predates the IBM i job-name fix | Upgrade the relay. |
Startup error about credentials.json keys | The file was edited or is out of date | Use the file exactly as downloaded. If you no longer have it, rotate the credentials (on the Credentials and Security tab) for a new one. |
Opaque 403 / 404 on startup | Wrong AGENT_SERVICE_URL or missing path prefix | Use the exact connection values shown in the register dialog. |
| Relay stays "unhealthy" | It never finished starting (credentials or connectivity) | Check the relay logs; verify the credentials and connection variables. |
| Legacy agents show Unknown (yellow) | The relay is stale/down, not the agents | Check the relay's health and connectivity first. |
A relay is healthy but runs no jobs; /health reads standby | Another copy of the same relay is active | Expected. Stop the copy you did not mean to run — see More than one relay process. |
| A relay keeps exiting with code 73, Another relay process is already running with state directory … | A second service or container on the host uses the same state directory | Stop the duplicate. |
| A legacy job works through one relay and not another | The relays run different builds | Compare their Version on the Relays tab with the version Download Relay offers, and upgrade the older one. |
| Deleting a relay says it is online, or stopped less than a minute ago, and still has jobs | Its jobs can be ended only once the relay has stopped | Stop the relay, wait one minute after it shows Offline, then delete it again. |
| A relay shows No Standby on the Relays tab | It runs as one process, so nothing takes over if that process stops | Start a second copy on another host with the same credentials.json. Just after a handover, wait for the previous active process to restart as a standby. |
| A standby has no Hand Over, or it is unavailable with The active instance cannot hand over … | The standby is not ready (stopped, not reporting in, or an older build), or the active process runs a build that cannot hand over | Start or upgrade the standby; or stop the active process cleanly and let the standby take over — see Hand over to a standby (on the Rename, Delete or Stop tab). |
| New Relay, Rotate Credentials, Hand Over or Delete is unavailable, with You do not have permission to … | Your roles do not grant that Relays permission | Ask for it — see Agents, agent pools and relays are checked. |
| Every legacy machine behind a relay went down after its LSAM Connector restarted, until the relay was restarted | The relay predates reconnecting machines after a connector restart | Upgrade the relay. |
Related topics
- Relays — full configuration reference and troubleshooting
- Manage agents and agent pools (Administrator)
- Prepare agents for connectors (Administrator)