Agents and agent pools
- Synopsis
- Full Details
In briefAn agent runs jobs on a machine: a Universal Agent runs the built-in connectors, and legacy agents are reached through a relay. Agent pools route work: a Universal Agent pool is a queue its agents claim jobs from, and a legacy agent group is a dispatch target for legacy job types. A job assigned to a specific agent can name up to three backup agents, and runs on the first available one when its primary cannot take it. Each agent shows its observed status and any operator mark you set.
WhereAgents in the navigation, with three tabs: Agents, Agent Pools and Relays, each at its own address. Selecting a row opens its edit dialog. Each tab needs its View permission under All workspaces.
When
- Registering a legacy agent under a relay, or grouping agents so jobs can run on whichever is available.
- Taking an agent out of service for maintenance with Mark Draining or Mark Offline, or resetting one agent's connection with Mark Offline then Clear Mark.
- Keeping a specific-agent job running when its agent goes down, by giving it backup agents.
- Checking a legacy agent whose Status shows a warning because its reported host name changed.
- Diagnosing a job held in Waiting: Machine, an Unknown or Offline agent, or a pool that takes no work.
- Use Relays for the relay itself, and the job type's own page for job settings.
How
- On the Agents tab, New Agent, choose the type, and fill in the form. A Universal Agent is registered through the API instead, and its program then signs in with the credentials file.
- On the Agent Pools tab, New Agent Pool, pick the Type, and add agents of that type.
- Assign the pool, group or agent to the job in the workflow. For a specific agent, turn on Configure backup agents to choose up to three backups.
- To service a machine, mark it from its row menu, and Clear Mark when you are done.
- For the full steps, see Manage agents and agent pools.
- A Universal Agent pool job is one job on the pool's queue, claimed by whichever agent polls first, whether the mode is least-tasked or run-all. A job assigned to a specific Universal Agent can run on any agent in that agent's pool.
- A Universal Agent obeys its own
MAX_CONCURRENT_JOBSsetting (default 50), not the Concurrent Jobs (max) figure on its row. - Use TLS for Scheduling on a Windows, Unix, IBM i, MCP, z/OS or OS 2200 agent has the relay connect to it over TLS. It needs relay 1.24.0 or later and TLS on at the agent, and never falls back to an unencrypted connection.
- Unknown means the agent's relay is stale, not that the agent is down. A job aimed at an Unknown agent holds in Waiting: Machine until the agent is Online again. If the relay stays gone for an hour, its Unknown agents read Offline.
- Backup agents are tried in order only while the primary is unavailable, and every run starts again from the primary. A job on a pool or group, a SMAFT File Transfer or OpCon RPA Task job, and a z/OS Tracked or Queued Job never use them. When no backup can take the job, it waits in Waiting: Machine, and it is never sent to an agent that cannot take it.
- SMAFT File Transfer and OpCon RPA Task jobs run on one specific agent only; the editor offers nothing else, and a save that sets a pool, a group or a backup agent on one is refused.
- A legacy agent's host-name warning is information only. It clears when you choose Accept Host Name, when the agent reports its earlier name again, or when you change its LSAM Host or LSAM Port.
- A mark survives a reconnect, warns but does not block when jobs are running, and takes effect within about five seconds.
- Mark Offline stops communication: the relay closes a legacy agent's connection within about a minute, and Clear Mark opens a new one. Running jobs keep running and report afterwards. Mark Draining keeps the agent connected.
- Check CRC (every legacy type) and Requires XML Escape Sequences (Windows, SQL, MCP) are set per agent; changing either from its default needs a current relay.
- A mark set by a
$MACHINE:STATUSevent a person sent shows that person as Set by; one a job, workflow or machine raised shows Set by system. - A clean stop shows offline in about a second. An abrupt loss takes about 90 seconds for a Universal Agent and two minutes for a relay.
- A newly registered Universal Agent reads Offline, with a last heartbeat of Never, until the agent program first checks in.
- BIS agents can be registered, but no job type runs on them.
- An MCP agent's name must end with a period and be at most 24 characters. A z/OS agent's name is saved in upper case, at most 8 characters.
- A blank JORS Port, or
0, turns JORS off for the agent. - A legacy agent's Concurrent Jobs (max) is not enforced.
- Machine Properties, in the footer of every Edit Agent dialog, holds the agent's own name
and value pairs, read by
[[MI.Name]]. Changing them needs Agents Edit under All workspaces, and the values are not encrypted. - An SAP agent's SAP system details are used by the SAP lookups in the job editor and by Check SAP Job Numbers, not by its jobs.
- Allow Kill is on by default for every killable legacy type except SAP R/3 and CRM, where it is off.
- Every action needs the matching Agents, Agent Pools or Relays permission, granted under All workspaces. A legacy agent group follows the Agent Pools permissions.
- The install commands shown for Universal in New Agent do not register an agent. Register it through the API and write its credentials file.
- Every Universal Agent job has a fixed one-hour limit, and Kill does not stop it.
- Kill on a legacy job is refused when its agent's Allow Kill is off, and always on SAP BW, OS 2200 and BIS agents.
- A legacy agent with no default event environment has every event it raises refused.
- File transfer is opt-in: until a legacy agent has an FT Role, it takes part in no SMAFT transfer.
- A pool or group that still has agents cannot be deleted.
- An agent that is online, has jobs on it, or is named by a workflow or an unfinished job cannot be deleted. Mark it offline and clear what the refusal lists first.
- A backup agent is not checked for the job's type: a backup that cannot run the job is refused it, as the primary would be. Only for OpCon MFT, OpCon RPA and EASE jobs is a backup on a relay with that kind of job turned off skipped.
- A legacy job whose machine name points at an agent of another type is refused at dispatch, with LSAM_AGENT_TYPE_MISMATCH.
Task walkthrough: Manage agents and agent pools. This page is the full configuration and troubleshooting reference.
An agent is the software that runs jobs on a machine. Agent pools group agents so jobs can be routed to whichever agent is available. The Universal Agent runs the built-in connectors; legacy LSAM machines are reached through the relay.
- The Agents Area
- Agent Fields
- Agent Types
- Legacy Agent Settings
- Service and Status
- Job Routing
- Troubleshooting
The Agents Area
The Agents item in the navigation opens one page with three tabs. Each tab is its own address, so you can bookmark or share it, and selecting a row opens its edit dialog.
| Tab | What it lists | Toolbar |
|---|---|---|
| Agents | Every agent in the tenant — Universal Agents and the legacy agents behind your relays — in one table | New Agent, and Delete once rows are selected |
| Agent Pools | Universal Agent pools and legacy agent groups together, told apart by Type | New Agent Pool, and Delete once rows are selected |
| Relays | Every relay. See Relays | New Relay, Download Relay, and Delete once rows are selected |
Each table pages and sorts on the server, 20 rows a page by default, and has a Name filter in its column header.
What you can see and do here depends on your roles. Each tab is shown only when your roles grant its View permission — Agents View, Agent Pools View or Relays View — under All workspaces, and a link to a tab you cannot see opens the first one you can. Every action needs the matching Create, Edit or Delete permission on the object it changes. An action you may not take is unavailable, and its tooltip says why, such as You do not have permission to create agents. A legacy agent group is governed by the Agent Pools permissions, and an agent shown under a pool or a relay by the Agents permissions. For every action and the permission it needs, see Agents, agent pools and relays are checked.
The Agents tab
| Column | Shows |
|---|---|
| Name | The agent's name. The filter matches the name or the host name. |
| Relay Name | The relay a legacy agent sits behind. N/A for a Universal Agent. |
| Platform | Universal, or the legacy type: Windows, Unix, IBM i, MCP, SAP R/3 and CRM, z/OS, SQL, OpCon MFT, OpCon RPA, EASE, SAP BW, OS 2200 or BIS. The filter selects any number of them. |
| Running Jobs/Concurrent Jobs (max) | The jobs the agent has in hand now, over its concurrency cap — see Running jobs. |
| Status | The status badge, with a warning icon beside it while a legacy agent's reported host name has changed, or while Mark Offline could not stop communication. The filter selects any of Online, Offline, Unknown, Marked Draining and Marked Offline, matching what the badge shows. |
| Version | The version the agent reports. A legacy agent shows the version its LSAM reports to the relay, and keeps the last one reported while it is offline. |
| Scheduling TLS | On or Off: whether the agent's Use TLS for Scheduling is turned on. — for an agent type that cannot use it. |
| Last Heartbeat | How long ago the agent last checked in; hover for the exact time. Never until it first checks in, and Not communicating while Mark Offline has stopped communication with it. |
Each row's menu offers Edit, Update (Universal Agents only), the three operator marks, Reset API token (OpCon MFT agents only), Accept Host Name (only while the agent's host-name warning is showing), and Delete. Deleting several agents at once deletes each one separately: any that fail are named in an alert and stay selected so you can try again. The alert groups failures that share a reason into one sentence, Could not delete "A", "B": reason. Deleting several pools or relays reports failures the same way.
An agent in use cannot be deleted
Every delete of an agent is checked first, whichever way it is made: from the Agents tab, from a row in Edit Agent Pool, or through the API, and for Universal and legacy agents alike. The delete is refused, and nothing is changed, when any of these holds:
| Refused because | What counts |
|---|---|
| It is still connected | The agent is observed Online and is not Marked Offline. Marked Draining does not count as offline. An agent that shows Offline or Unknown passes |
| Jobs are waiting or running on it | Work sent to the agent that is waiting to be picked up, claimed, running, or shown as Lost in Failover. A legacy agent's work is matched through its relay, by the agent's name |
| Workflows use it | The current version of a workflow has a job that names the agent as its agent or one of its backup agents, or a SMAFT job that names it, ignoring case, as its source or destination machine |
| Unfinished jobs use it | A job instance in any environment that has not ended names the agent the same ways, or ran it as the member a legacy group picked. A job that finished, failed, was cancelled, skipped or missed its start time does not count, and neither does a job left waiting in a workflow instance that has completed or been cancelled |
The first two are checked first. When either refuses, the workflows and unfinished jobs are not looked at yet, so they appear only once the agent is offline and idle.
Deleting one agent. A refused delete opens Delete Agent with an OK button. It reads
"<name>" is in use, so it cannot be deleted yet., then the reasons that apply:
- Mark it offline first.
<N>jobs are waiting or running on it.- Workflows that use it: each as
<workflow>:<job>, and a Unfinished jobs in<environment>: list for each environment, each as<workflow>(<schedule date>):<job>. A backup agent is marked (backup agent), a legacy group member (group member), and a SMAFT endpoint (file transfer source) or (file transfer destination). Each list shows up to 20, then and<N>more.
It ends by saying what to do, for example Remove it from the workflow jobs listed, then delete the agent again.
Deleting several. The agents that can be deleted are deleted. Each refused one stays selected
and is named in the alert with a short reason: still online, <N> jobs waiting or running, in
use by <N> workflow jobs or in use by <N> unfinished jobs.
When the check cannot finish, nothing is deleted. If the workflows or any environment's jobs cannot be checked, the delete is refused rather than let through. Deleting one agent keeps the confirmation open with the reason, and Delete tries again:
| Message | Means |
|---|---|
The delete could not be checked: environment '<name>' did not answer. Try again later. | That environment's jobs could not be read just then. It names the workflow lookup or the environment list instead when one of those could not be read. A single environment that does not answer blocks every agent delete until it does |
The delete could not be checked: you do not have permission to view the jobs in environment '<name>'. Ask an administrator to delete the agent. | The check reads unfinished jobs in every workspace with your own permissions, and your roles do not grant Job Instances View in every workspace of that environment |
In a delete of several, an agent that could not be checked is listed as could not be checked.
Edit opens a dialog that depends on the kind of agent:
- A Universal Agent's dialog is read-only, with Delete and Close. It shows the machine
identifier (the host name), agent version, last heartbeat, current jobs, operating system, Docker
and the detected runtimes; Docker reads Not available when the agent reports no Docker.
Client ID, Last Work Completed, CPU Cores, Memory and Free Disk read
--, and Installed Plugins reads No plugins reported: the dialog does not display these values, whatever the agent reports. - A legacy agent's dialog is its full registration form, with Save Changes. Its type and its
relay are shown but cannot be changed. A legacy LSAM agent's dialog also shows its read-only
Reported Host Name (
—until the agent reports one).
The host name a legacy agent reports
A legacy LSAM agent reports the host name of the machine it runs on. Continuum keeps the last one each
agent reported and compares every new report with it, across relay restarts and a relay handing over
to another instance. When the name changes, the agent's Status shows a warning icon; hovering it
reads Host name changed from <previous> to <current> on <time>. The agent may be reaching a
different machine. — a sign that the connection may now reach a different machine than before, for
example after an address change behind the agent's host name.
The warning is information only: jobs, the agent's status and dispatch are not affected. It clears when:
- someone chooses Accept Host Name from the agent's row menu and confirms — This agent now
reports host name
<current>instead of<previous>. Accepting it clears the warning. If the name changes again before you confirm, the dialog says The host name changed again. Close this dialog to see the new value.; - the agent reports its earlier host name again; or
- you change the agent's LSAM Host or LSAM Port, which also clears the stored name, so the next report starts afresh.
Universal Agents and the OpCon MFT, OpCon RPA and EASE agents report no host name. A relay older than this release does not pass the name on, so its agents show none.
While any legacy agent has no default event environment, the tab shows a warning — N classic agents have no default event environment. Every event they raise is rejected until one is set. — with Assign environment…, which sets one environment on all of them at once. See Events raised by a legacy agent.
New Agent asks you to Choose Agent Type. Universal shows install instructions — read
Registering a Universal Agent before you use them. Any other type
shows the legacy agent form: Name, Relay, Agent Pools (the legacy agent groups of the
same type to add it to), the host and ports, Concurrent Jobs (Max) (1 to 1,000; it starts at 50, as in Classic), the type's own
fields, Allow Kill for the types that offer it, and Default event environment. If the agent is created but adding it to a group fails,
the dialog says so and keeps only Agent Pools editable, so Save again retries just that.
The ports start at the type's defaults. LSAM Port starts at 3100, and JORS Port starts
empty, for every legacy LSAM type that has one except SAP R/3 and CRM, which starts at 13100 and 13110,
and SAP BW, which starts at 14100 and 14110 — the defaults of each SAP agent's installer. An
SAP BW agent registered earlier on the defaults kept 13100 and 13110, which are not the SAP BW
agent's own; if it never connects, set its ports to the ones the agent listens on. An OpCon MFT, OpCon RPA or EASE agent shows
HTTPS Port instead, with no JORS port. A BIS agent has no JORS Port either, because a
BIS agent has no JORS listener: a port sent for one through the API is refused with jorsPort cannot
be set on BIS agents: they have no JORS listener, and any port a BIS agent held from earlier has
been cleared. Changing the type swaps a port only while it still holds a
default, so a port you typed is kept. An agent registered through the API without a port takes the
same defaults.
Leave JORS Port blank, or enter 0, to turn JORS off — the hint under the field says For job
output retrieval. Leave blank or enter 0 to turn it off. Either way no port is stored, so after a
save the field shows blank. That holds on an agent you edit too: clearing the field removes the
port the agent held. On a new SAP R/3 and CRM or SAP BW agent, clearing the prefilled port
turns JORS off rather than falling back to the type's default. Any other value must be 1 to 65535,
or the form shows Port must be 0 (off) or between 1 and 65535. Through the API, 0 is accepted
for every type, including BIS, and is stored as no port.
A job's output is listed through the JORS Port. Until it is set, a job on the agent cannot list its output: the job's Output tab says JORS port not configured for agent: …, naming the agent. That is where a z/OS agent starts — see Its output. A z/OS agent's JCL is read and saved through the same port, so JCL access needs it too.
SAP R/3 and CRM and SAP BW agents also have a Query Listener Port — The port the agent
listens on for design-time requests. Must match the agent's configuration. Blank means the platform
default, shown under the field: 13101 for SAP R/3 and CRM and 14101 for SAP BW. A value
must be 1 to 65535, or the form shows Port must be between 1 and 65535. No other type shows it.
The relay connects to this port for the SAP lookups in the job editor and for
Check SAP Job Numbers; a wrong value makes them
fail with The agent's query port could not be reached.
A type with settings of its own gets a section for them, named after the type — SAP R/3 and CRM settings and SAP BW settings: see SAP system details and SAP events to monitor.
BIS agents can be registered, grouped, and connected through a relay, but no job type in this build runs on them, so they cannot be given work. SAP R/3 and CRM agents run the SAP R/3 Job type, SAP BW agents the SAP BW Process Chain type, z/OS agents the four z/OS types, MCP agents the six MCP types, and OS 2200 agents the OS 2200 Job type. A job of another platform's type pointed at one of them is refused when it is dispatched — see A legacy job aimed at an agent of another type.
MCP agent names
An MCP agent's name must end with a period (.) and be at most 24 characters, such as
MCPPROD., as the MCP LSAM expects. Creating an MCP agent with any other name, or renaming one to
it, is refused with MCP agent names must end with a period (.) and be at most 24 characters; the
New Agent form shows the same message under Name. An MCP agent registered before the rule
keeps its name, and can be edited without renaming it.
z/OS agent names
A z/OS agent's name is saved in upper case, and is at most 8 characters, as the z/OS LSAM
expects. The New Agent form says so under Name — Saved in upper case, at most 8
characters — and upper-cases the name when you save, so zprod1 is saved as ZPROD1. Creating a
z/OS agent with a longer name, or renaming one to it, is refused with z/OS agent names must be at
most 8 characters, and the form shows the same message under Name. The same rules apply to an
agent created or renamed through the API.
Because the name is upper-cased before it is checked against the relay's other agents, a new
zprod1 clashes with an existing ZPROD1. A z/OS agent registered before the rule keeps its name,
and can be edited without renaming it. The name every other agent type is given is kept as typed.
The Agent Pools tab
| Column | Shows |
|---|---|
| Name, Description | The pool's or group's own. The filter matches either. |
| Type | Universal for a Universal Agent pool, or the legacy type of a legacy agent group. |
| # of Agents | Its agents. |
| Online | Its agents that are observed online and carry no operator mark — the ones that can take work. |
| Running Jobs/Concurrent Jobs (max) | Its agents' running jobs added up, over their caps added up. |
The pools that relays dispatch through are not listed: they are not pools you manage.
New Agent Pool has a Name, a Type (Universal by default) and a Description. Name and type cannot be changed after creation. Add Agent(s) to Pool opens a searchable picker of the agents of that type; Commit Selected Agents stages them, and Save creates the pool and adds them in one step — if any of them can't be added, nothing is created. Changing Type after staging agents asks first, then removes them.
Edit Agent Pool saves only the description with Save. Changes to its agents apply at once: New Agent (its type fixed to the pool's), Add Agent(s) to Pool, and, on each agent's row, Remove from Pool and Delete.
| Difference | Universal Agent pool | Legacy agent group |
|---|---|---|
| Name | Lowercase letters, digits and -, starting with a letter or digit, up to 255 characters — a naming exception | Letters, digits, ., _ and -, up to 255 characters |
| An agent belongs to | One pool. Adding it to a pool moves it out of its current one | Any number of groups of its type. Adding it leaves its other groups alone |
| Remove from Pool | Moves the agent to the pool named default-cloud, because a Universal Agent always has a pool. Not offered on that pool's own rows. When no pool with that name exists it is shown disabled, with There is no default-cloud pool to move this agent to. | Takes the agent out of the group |
A Universal Agent moved to another pool starts taking work from it at its next sign-in refresh — up to about 15 minutes later with the default settings. Until then it keeps taking work from its old pool.
A pool or group that still has agents cannot be deleted. Its row's Delete is disabled with Remove all agents before deleting this pool., a delete of several selected pools skips those with agents and names them, and a request that gets through anyway is refused with Agent pool '…' has N agent(s); remove them first (or Agent group '…' for a legacy group). Deleting a legacy group never deletes its member agents.
Running jobs
Running Jobs counts the work an agent has claimed or is running right now. A job waiting on a pool's queue for an agent is not counted. A legacy agent's work is claimed by its relay, so it is matched to the agent by the machine the job was sent to. The same count drives the warning when you mark an agent that has jobs running.
Concurrent Jobs (max) is the value stored on the agent. For a legacy agent it is the
Concurrent Jobs (Max) you set, and it is a figure, not a limit: nothing in this build holds a
legacy agent's jobs back when its running jobs reach it, and the connection to the agent sets no
limit of its own. For a Universal Agent it is set to 1 at registration and has
no control in the Agents area — and it is not the cap the agent obeys, which is its own MAX_CONCURRENT_JOBS
setting (see Registering a Universal Agent). A Universal Agent can
therefore show more running jobs than its maximum.
The pool list has no queued-jobs count. The Agent Pool Job Queue dashboard widget shows how much work is waiting.
Agent Fields
Agent pool
| Field | Notes |
|---|---|
| Name | Unique; cannot be changed after creation. For a Universal Agent pool, up to 255 characters, lowercase letters, digits and - only, starting with a letter or digit — a pool name is an identifier, so it is one of the naming exceptions. |
| Description | Optional, editable. |
Agent
| Field | Values / notes |
|---|---|
| Name, host name | Identity. A Universal Agent's dialog shows the host name as Machine Identifier; a legacy agent's form calls it LSAM Host, or Host (EASE Host for an EASE agent). |
| Operating System | Windows, Linux or macOS, followed by the architecture (x64 or arm64) in brackets, for example Linux (x64). |
| Agent Version | Installed agent version. The Version column on the Agents tab. |
| Platform | The agent's type: Universal, plus the legacy types Windows, Unix, IBM i, MCP, SAP R/3 and CRM, z/OS, SQL, OpCon MFT, OpCon RPA, EASE, SAP BW, OS 2200 and BIS. The type once called SAP is now SAP R/3 and CRM: existing SAP agents and groups were renamed, and the old SAP type is no longer accepted. OS 2200 and BIS agents have no job type that runs on them. |
| Status | Observed connectivity: Online, Offline, Unknown. Unknown = reachability can't be determined — usually relay-down (the agent's relay went stale), or the relay itself reports it cannot tell — distinct from Offline = agent-down. Shown yellow, with a text label. Applies to legacy LSAM agents reached via a relay. Busy and Draining are also in the status list, but nothing in this build sets either, so an agent never shows them. |
| Operator State | What you asserted, independent of what the platform observes: Active (the default), Marked Offline, Marked Draining. See Taking an agent out of service. |
| Effective Status | The single value the UI and reports show, derived from the two above. An operator mark always wins — there is no case in which observed status overrides one. |
| Update Status | Whether the agent is up to date, has an update available, is updating, or failed its last update. |
| Last Heartbeat | Last check-in. A legacy agent shows Never until its relay first reports it. A Universal Agent shows Never until the agent program first checks in: registering it records no heartbeat and the status Offline, and its first heartbeat turns it Online. So a Universal Agent that reads Online has really checked in. |
| Running Jobs/Concurrent Jobs (max) | The job count stored on the agent is never updated after registration, so it is not shown; the Agents area counts running jobs from the work itself instead. Concurrent Jobs (max) is the cap stored on the agent. For a Universal Agent it is set to 1 at registration, has no control in the Agents area, and is never sent to the agent: the agent runs up to the number set in its own MAX_CONCURRENT_JOBS environment variable — 50 if it is not set. See Registering a Universal Agent. |
| Runtimes | Detected runtimes: node, python, dotnet, java, powershell. Docker is reported separately, as whether it is available and its version. |
| Default event environment | Legacy agents only. The one environment that events this machine raises are applied to. Required when you register every legacy type except OpCon MFT and OpCon RPA, and can be cleared only by an edit; while it is unset every event that machine raises is refused — see Events raised by a legacy agent. Set it on the agent's New Agent or Edit Agent dialog on the Agents tab; clearing it back to unset stops the channel. |
| File Transfer (SMAFT) | Legacy agents of the types that can take part in a file transfer only — Windows, Unix, IBM i, MCP, z/OS and OS 2200. A Universal Agent has none, and it is not offered for an SQL, SAP R/3 and CRM, SAP BW, BIS, OpCon MFT, OpCon RPA or EASE agent. The machine's file-transfer address, ports, role, and TLS switches. See File-transfer endpoint. |
| API Token | OpCon MFT and OpCon RPA agents only. Whether an API token is stored for the agent. The token itself is never returned by any read. See OpCon MFT Transfer job and OpCon RPA Task job. |
| EASE settings | EASE agents only — none for every other type. The non-secret connector settings: Customer Id, EASE Schedule Name, EASE User, Local Event User, Time Zone and Debug Mode, plus a local schedule name that has no field on the form. An update through the API replaces them wholesale, so send every setting you want to keep. See EASE jobs. |
| EASE Password, Local Event Token | EASE agents only. Whether each of the two EASE secrets is stored. Neither value is ever returned by any read. |
A Universal Agent's Edit Agent dialog shows CPU cores, memory, free disk, client ID and last
work completed as --, and Installed Plugins as No plugins reported: the dialog does not
display them, whatever the agent reports.
Machine properties
Every agent, of every type, can carry its own list of machine properties: name and value pairs
such as EMAIL or PYTHON_PATH that describe that one machine. Jobs, events and notifications read
them with [[MI.Name]] tokens — see
Machine properties in a token — and $PROPERTY events
write them — see Writing a machine property. The list
belongs to the agent, so every environment sees the same values.
Where. Open the agent's Edit Agent dialog from the Agents tab and select Machine Properties in its footer. It opens a Machine Properties dialog for that agent, with the agent's name under the title and one row per property, sorted by name ignoring case. An agent with none shows No machine properties.
- Add Property adds a row; each row has a Name, a Value, and a remove button.
- Save sends only the rows you added, changed or removed, then closes the dialog with Machine properties saved. A value an event wrote to another property while the dialog was open is kept.
- If the save fails, the dialog stays open with the reason. When a property you changed was removed in the meantime, Reload reads the list again, and drops your edits.
Who. Anyone who can open the Edit Agent dialog can open the list and read it. Changing it needs Agents Edit under All workspaces: without it the rows are read-only, Add Property is not shown and Save is unavailable.
The rules, applied in the dialog and again when the change is saved:
| Rule | Detail |
|---|---|
| Name | Required, at most 256 characters, and none of ' ( ) \ , = ; |. A dot and a / are allowed. A name the platform supplies, such as $MACHINE NAME, is refused with This name is reserved for a system property. |
| Unique, ignoring case | Two rows whose names differ only in case cannot both be saved: Same name as '<name>' (case is ignored). |
| Value | At most 4,000 characters, and may be empty |
| Spaces | Leading and trailing spaces are removed from names and values |
| How many | At most 200 properties per agent. At 200, Add Property is unavailable, and one save takes at most 200 changes |
Values are stored and shown as plain text, and any job, event or notification that names the token
can read them. Keep credentials in an encrypted property instead. A $PROPERTY
event that copies an encrypted property's value into a machine property is refused.
The agents API reads, replaces and changes the same list, at /api/v1/agents/<id>/properties.
Agent Types
Registering a Universal Agent
Choosing Universal in New Agent shows install commands for Windows, Linux and macOS, and says
the agent registers itself with the default-cloud pool on first connection. Neither holds in this
build: the agent program has no configure or install command, and it does not register
itself when it first connects. The dialog saves nothing; it only has Close.
A Universal Agent is registered through the API, and the agent program then signs in with the credential that registration returns:
- Register the agent. An authenticated call to the agent registration endpoint,
POST /api/v1/agents/register(behind the environment's/agent-apipath prefix in the cloud), names the agent and the pool it joins and describes the machine —name,agentPoolId,hostname,os,architecture,agentVersion. Agent names are unique in the tenant. The response returns the new agent and aclientIdandclientSecret. The secret is returned only in that response — it is stored hashed and cannot be read back. - Write the credentials file on the agent machine. At startup the agent reads a JSON file with
exactly four keys —
agentId,agentPoolId,clientId,clientSecret— and refuses a file with any other key. The default location is~/.opcon-agent/credentials.jsonfor the account the agent runs as;CREDENTIALS_FILEchanges it. Restrict the file to that account — the agent logs a warning at startup when the file's mode is anything other than0600. - Point the agent at the platform and start it. Set
AGENT_SERVICE_URL, andAGENT_SERVICE_PATH_PREFIX(for example/agent-api) when the platform is reached through the cloud edge, then runopcon-agent start.
An agent with no credentials file stops at startup with Agent not registered. The program's only
other commands are opcon-agent version and opcon-agent status, which reports the agent and pool
IDs from the credentials file.
| Agent environment variable | Default | What it sets |
|---|---|---|
AGENT_SERVICE_URL | http://localhost:3007 | The platform's agent service. |
AGENT_SERVICE_PATH_PREFIX | empty | Path prefix for the cloud edge, for example /agent-api. |
CREDENTIALS_FILE | ~/.opcon-agent/credentials.json | Where the credentials file is read from. |
MAX_CONCURRENT_JOBS | 50 | How many jobs the agent runs at once. Earlier builds defaulted to 5. This, not the Concurrent Jobs (max) figure on the agent's row, is the cap a Universal Agent obeys. |
HEARTBEAT_INTERVAL_MS | 30000 | How often the agent checks in. |
How a Universal Agent takes and runs work
These apply to every job type a Universal Agent runs — Run Command, Run Script and Wait for File:
- Every job has a fixed one-hour limit. The platform sends every job with a timeout of 3,600 seconds, and there is no job setting that changes it. At the hour the agent stops the process (a graceful stop, then a forced stop five seconds later) and the job fails. A Wait for File job stops waiting at the hour.
- The agent takes new work whenever it has a free slot. Each time it polls, the agent takes
as many jobs as it has free slots for, up to 10 at a time, and polls again straight away while
slots are free, so it can run up to its
MAX_CONCURRENT_JOBSat once. Earlier builds waited for every job in a batch to finish before polling again, so an agent never ran more than 10 jobs at once, and one long-running job kept it from picking up new work. - A busy platform does not fail a job. If the platform is too busy to accept the agent's claim on a job, the job is offered again rather than failed. Earlier builds failed it.
- Kill does not reach a Universal Agent. The job's status records the kill request, but the process on the agent keeps running until it ends on its own or reaches the one-hour limit. Kill stops work only on legacy agents, through their relay.
OpCon MFT agents
An OpCon MFT agent is registered under a relay, with New Agent on the
Agents tab and the same form as a legacy LSAM machine, but it is not an LSAM. Three fields on the dialog differ: the host and port
are labelled Host and HTTPS Port (default 41100), there is no JORS Port because there
is no JORS listener, and there is an API Token. It also has no file-transfer endpoint, so it can
be neither end of a SMAFT transfer.
On the Agents tab an MFT row shows OpCon MFT as its platform and the version the agent reports. Its actions menu carries one extra item, Reset API token.
Full detail — registering one, what the token is for, and what a reset invalidates — is on OpCon MFT Transfer job.
OpCon RPA agents
An OpCon RPA agent is registered the same way and is likewise not an LSAM. The dialog
differs in the same three places — Host and HTTPS Port (default 7047), no JORS Port,
and an API Token — and it too has no file-transfer endpoint, so it cannot take part in a
SMAFT transfer.
Two things differ from an OpCon MFT agent:
- The token must be a GUID, and it is what makes the agent usable at all: an RPA agent with no token stored reports DOWN, because the relay has nothing to authenticate with.
- There is no Reset API token action. Continuum cannot mint an RPA token — it is configured on the agent itself, and Continuum only stores a copy. The edit dialog offers Clear token to remove the stored copy instead.
On the Agents tab an RPA row shows OpCon RPA as its platform and the version the agent reports. Its health is checked directly against the agent roughly every 10 seconds, and is deliberately not tied to whether the agent's own robot clients are connected.
Full detail — registering one and what the token is for — is on OpCon RPA Task job.
EASE agents
An EASE agent is the third kind registered under a relay without being an LSAM, and it is the one that is not a machine of yours: it is Jack Henry's hosted EASE OpCon, reached over its REST API. It has no JORS port and no file-transfer endpoint, so it cannot take part in a SMAFT transfer.
Two things make its dialog different from the other two:
- There is no API Token. An EASE agent authenticates with its own credentials — an EASE User and EASE Password — stored in an EASE Datacenter group on the form, alongside a Customer Id, an EASE Schedule Name and an optional Time Zone. A second group, Local (Continuum) events, holds the event user and token the SEQ property write-back uses. Both secrets are write-only.
- Its Default Event Environment means something narrower. An EASE agent has no MSGIN directory; the setting governs the one event it raises, the SEQ property write-back.
On the Agents tab an EASE row shows EASE as its platform and the EASE OpCon's own REST API
version as its version. Its HTTPS port defaults to 443. Its health is probed directly against
the EASE OpCon roughly every 10 seconds, and an agent with no Customer Id or no EASE Schedule
Name reports DOWN without a call being made. The probe sends no credentials, so a wrong
EASE Password leaves the agent UP and fails its jobs at start.
Full detail — registering one, every field and its limits — is on EASE jobs.
Legacy Agent Settings
File-transfer endpoint (legacy agents)
A SMAFT File Transfer job connects one legacy machine directly to another. That is a different network path from the one the relay uses, and a different set of questions — which direction a machine may take part in, which port to dial, whether TLS is possible. Those answers live on the agent, as its file-transfer endpoint.
You configure it on an existing legacy agent: open the agent on the Agents tab, then the File Transfer (SMAFT) section. It is not offered while registering a new agent — register the machine first, then set its endpoint.
The agent does not report these values and they are not read from your Classic configuration. An administrator sets them, which is also how Classic works.
| Field | Default when blank | Notes |
|---|---|---|
| FT IP Address | the agent's LSAM host | The address the other agent connects to for a transfer. Often different from the LSAM host, which only the relay uses. A hostname or IPv4 address only — no port, scheme, path, or spaces. |
| FT Port (non-TLS) | 3110 on Windows; 3108 on UNIX, IBM i, MCP, z/OS and OS 2200; none on SQL, SAP R/3 and CRM, SAP BW and BIS | 1–65535. |
| FT Port (TLS) | unset — there is no platform default | 1–65535. A transfer that asks for TLS cannot resolve a port until this is set. |
| FT Role | None - never a file-transfer participant | Source only, Destination only, Both source and destination, or None - never a file-transfer participant. Decides which machine pickers the agent appears in. File transfer is opt-in — see below. |
| Supports non-TLS transfers | on | Both ends must permit a mode for a transfer to use it. |
| Supports TLS transfers | off |
Full file-transfer support, which is what a push (Start Transfer On = Source) requires on
both machines, is part of the endpoint and defaults to enabled. It has no control in this
build's interface — it is reachable only through the API — so in practice every registered legacy
machine can take part in a push until one is changed deliberately.
Inherited or overridden
Every field is empty when nothing is stored, and the hint under it reads the effective value —
Inherited - currently 3108 (default for this platform) — rather than pre-filling it. That is
deliberate: a pre-filled form would freeze today's defaults in as explicit overrides the first time
you saved it.
Each hint states the value the way you would read it in the list beside it, not the way the
protocol carries it — so the role's hint reads
Inherited - currently None - never a file-transfer participant (default for this platform).
Once you store a value the hint reads Override - stored as … instead. Clearing the address, a
port, or the role empties the field and returns it to inheriting the default. The two TLS switches
cannot be returned to inherited from the interface — a switch has no "unset" position to show — so
once toggled they stay stored.
FT IP Address is reached agent-to-agent, not by the relay, so an address that works for the relay is not evidence it works for a transfer. If a transfer fails to connect while both machines report online, check this field before anything else.
FT Role inherits None when nothing is stored, so a machine only becomes eligible for a transfer once an administrator gives it a role. That includes agents registered before the file-transfer endpoint existed: no role was backfilled for them, so each one participates in nothing until you set one.
A job that names a machine with no role saves normally and fails at dispatch, naming the machine and telling you which role to set. If a machine you expect is missing from the Source Machine or Destination Machine list, its role is the first thing to check.
A machine whose role is None never appears in either picker and can never take part in a transfer. A Universal Agent has no endpoint at all and is never offered.
A SQL, SAP R/3 and CRM, SAP BW or BIS machine has no file-transfer capability either. These are the legacy platforms with no default non-TLS port, so each resolves to none rather than inheriting the UNIX 3108, and never appears in a transfer's machine pickers. Their agents' forms do not show the File Transfer (SMAFT) section at all, and saving one leaves any endpoint values stored earlier as they were.
SAP system details
The SAP R/3 and CRM settings and SAP BW settings sections, on both New Agent and an existing agent's dialog, record the SAP system the agent connects to. The section opens with SAP system details must match the agent's own SAP configuration. They are sent with design-time SAP queries, and saving them never reconnects the agent.
| Setting | SAP R/3 and CRM | SAP BW | Values |
|---|---|---|---|
| Client ID | Yes | Yes | A whole number from 0 to 999. Blank means 0. |
| Gateway | Yes | Yes | The SAP application server address or SAP router string. Up to 4,000 characters. |
| System Number | Yes | Yes | A whole number from 0 to 99. Blank means 0. |
| R3 Name | Yes | Yes | The SAP system name, for load-balanced connections through a message server. Up to 4,000 characters. |
| Group | Yes | Yes | The SAP logon group, for load-balanced connections through a message server. Up to 4,000 characters. |
| RFC Trace | Off, Terse, Normal or Verbose | Off or On | Blank means Off. |
| Audit Level | Off, Terse, Normal or Verbose | Not shown | Blank means Off. |
Text values are stored without leading or trailing spaces, and a value left blank is not stored. A number out of range reads Enter a whole number from 0 to 999. (or from 0 to 99.) on its field, and nothing is saved until it is fixed.
The agent signs on to SAP with them when it answers an SAP query: the SAP lookups in the job editor and Check SAP Job Numbers. Details that do not match the agent's own SAP configuration make those fail — for example with The agent closed the connection without answering. Check the agent's SAP system settings. They are not sent with the agent's jobs, so saving them does not change how its jobs run.
OS 2200 Job Start Format
An OS 2200 agent's form, on both New Agent and an existing agent's dialog, has an OS 2200 settings section holding Job Start Format, beside Check CRC. It chooses how the agent's OS 2200 Jobs are started — the main runstream, a prerun and file dependencies alike. The section opens with Changes apply to jobs started after you save.
| Value | Use it for |
|---|---|
| XML | Current OS 2200 LSAMs. This is the default: an agent with nothing set shows Default (XML) and starts its jobs in XML. |
| Non-XML | Use Non-XML only for older OS 2200 LSAMs. The job start is sent in the older non-XML record, for an LSAM that cannot read XML. |
Clearing the field returns the agent to the default, XML. No other agent type shows the setting.
A change applies to the next job that starts, with no restart of the relay or the agent and no reconnect: the relay picks it up on its next check-in, about half a minute later. A job already started keeps the format it was started with.
XML needs a current relay. A relay that has not reported it can start OS 2200 jobs in XML refuses every OS 2200 Job for an agent set to XML — which, by default, is every OS 2200 agent. The job goes to Initialization Error with RELAY_LSAM_FEATURE_UNSUPPORTED: relay '…' (agent pool '…') has not reported support for the XML job start format on OS 2200 jobs. Upgrade the relay, or set the agent's Job Start Format to Non-XML. Jobs for agents set to Non-XML run on any relay. Upgrade every relay that serves an OS 2200 agent — see Keeping a relay current — or set the agent to Non-XML to run its jobs now.
Two character sequences cannot be sent in XML. On an agent set to XML, a job value that contains
</F> or <F I= is refused at dispatch, naming the field, and the job fails without running, as
on UNIX — see UNIX values reach the agent exactly as you typed them.
SAP events to monitor
An SAP R/3 and CRM agent can watch for SAP events and, when one occurs, raise OpCon events of your choosing. The list is on the agent form, in a section titled SAP R/3 and CRM settings, on both New Agent and an existing agent's dialog: SAP events to monitor — SAP events the agent watches for. When one occurs, the agent raises the OpCon events you list for it.
Add SAP event adds an entry; each entry's Remove takes it out again. An entry has:
| Field | Required | Limits | Notes |
|---|---|---|---|
| Name | No | ≤64 chars | A label for this entry. |
| SAP event | Yes | ≤32 chars | The SAP event to watch for. |
| Parameter | No | ≤64 chars | Leave blank to match the SAP event with no parameter. |
| OpCon events | Yes | 1 to 20 events, each ≤1,000 chars | One OpCon event per line, up to 20. Blank lines are dropped. |
The list holds up to 200 entries; at that point Add SAP event is unavailable, with You can monitor up to 200 SAP events. Two entries cannot share the same SAP event and Parameter — the second reads SAP event N already uses this SAP event and parameter. — and the values may hold only printable Latin-1 characters. A problem is shown on the field and nothing is saved until it is fixed.
Changes take effect when you save, whether the agent is online or not: Changes to Check CRC, SAP events to monitor are sent to the agent when you save. If the agent is connected, its connection is re-established automatically. The line names Check CRC as well, because it sits in the same section and reconnects the same way. Saving an unrelated change to the agent leaves the list untouched. Removing every entry and saving clears it, with one caveat the form states: The agent keeps watching its previous SAP events until it is restarted.
The events the agent raises are applied to the agent's Default event environment, like every other event a legacy machine raises — see Events raised by a legacy agent.
Use TLS for Scheduling (legacy agents)
A Windows, Unix, IBM i, MCP, z/OS or OS 2200 agent can have its relay
encrypt the connection it uses to schedule the agent's jobs and to fetch their output, and check the
agent's certificate before it sends anything. The agent form, on both New Agent and an existing
agent's dialog, shows a Use TLS for Scheduling switch for those types, after the file-transfer
settings and before Allow Kill: Encrypts scheduling and job output traffic. Must match the
agent's configuration. It is off for a new agent and for every agent that existed before it.
No other agent type shows it, and the platform refuses it on any other type with Use TLS for
Scheduling is not available for <type> agents.
Turning it on shows two more settings:
| Setting | Default | What it does |
|---|---|---|
| TLS Server Name | Blank | The name the agent's certificate must carry. Leave blank to use the LSAM host. — the agent's address as you entered it. Enter a host name or an IP address, up to 253 characters; anything else reads Enter a host name or IP address. For an agent registered by IP address, use a certificate that carries that address, or set a name here that the certificate does carry. |
| Check Certificate Revocation | Off | Also checks, online, that the agent's certificate has not been revoked. The relay must be able to reach the revocation service. |
The agent must have TLS turned on in its own configuration too. The relay never falls back to an unencrypted connection: if the agent does not answer in TLS, or its certificate does not check out, the agent stays offline until the two sides agree. Only TLS 1.2 and TLS 1.3 are used.
It needs a current relay. Turning the switch on is refused while the agent's relay has not
reported that it can make TLS scheduling connections: Relay <name> has not reported support for
TLS scheduling connections. Upgrade the relay. Relay 1.24.0 is the first release that does — see
Keeping a relay current. Most relays need nothing else: an
agent certificate issued by a certificate authority the relay's host already trusts works as it is.
To use your own certificate authority, or to present a client certificate to an agent that asks for
one, set the relay's scheduling TLS variables.
A change applies without a restart. At its next check-in the relay reconnects the agent with the new setting. Turning the switch off keeps the TLS Server Name and Check Certificate Revocation you set, unused, so turning it back on shows them again. The agent's change history records the switch and the revocation check, but not the server name.
When it fails. A TLS agent that cannot connect stays offline, and the relay's log names the reason, once per agent until it connects — see Scheduling TLS variables. Fetching a job's output from a TLS agent fails in the same way, with a reason that starts TLS:, rather than being fetched unencrypted.
Viewing and saving a z/OS agent's JCL is not available while the switch is on: the JCL dialog says JCL cannot be viewed or saved for this agent because it uses TLS for scheduling. — see Viewing and editing JCL. Jobs on the agent still run.
Allow Kill (legacy agents)
Each legacy agent decides whether an operator may Kill the jobs running on it. The legacy agent form shows an Allow Kill switch for the types that can be killed, and it starts at the agent's current setting:
| Agent type | Allow Kill | Default |
|---|---|---|
| Windows, Unix, IBM i, MCP, z/OS, SQL | Switch shown | On — every job that could be killed before stays killable |
| SAP R/3 and CRM | Switch shown | Off — Kill is refused until you turn it on |
| SAP BW, OS 2200, BIS | No switch | Their jobs can never be killed |
| OpCon MFT, OpCon RPA, EASE | No switch | Not affected — Kill behaves as it always has |
The hint under the switch says where the value comes from: Platform default: on (or off) while the agent follows its type's default, and Overrides the platform default (on) once you have changed it. While the agent overrides the default, Use platform default returns it to following the default. An agent you never change keeps following the default, and changing Type while creating an agent resets the switch to the new type's default.
What a refused kill looks like. Kill on a job whose agent does not allow it is refused, and nothing about the job changes: it keeps running and does not move to Running (To Be Terminated). The message names the reason:
| Message | When |
|---|---|
| Cannot kill: agent '…' does not allow its jobs to be killed. Turn on Allow Kill for the agent to kill jobs on it. | The agent's Allow Kill is off |
| Cannot kill: jobs on SAP BW agents cannot be killed (agent '…'). (or OS 2200, BIS) | The agent's type can never be killed |
| Cannot kill: the job's agent '…' matches more than one member of its group. | A legacy-group job whose agent name matches two members of the group |
| Cannot kill: the agent's kill setting could not be checked because agent-service is unavailable. Try again. | The setting could not be read at that moment. Nothing was changed, and you can retry |
OS 2200 and SAP BW jobs are refused from the job's own type, before the agent is looked up, so the refusal does not depend on the agent record or on agent-service being reachable. In the job lists, Kill is then unavailable for those jobs: the row menu shows the reason Jobs on OS 2200 agents cannot be killed. (or SAP BW), and the bulk action bar leaves Kill out when the selection holds one. The relay also sends no kill request to a machine whose agent type is OS 2200, BIS or SAP BW, whichever way the kill was raised.
For a job dispatched through a legacy agent group, the check is made against the member the job was sent to. A group job that has not been given a member yet is not checked.
Check CRC and Requires XML Escape Sequences (legacy agents)
Two switches tune how the relay talks to one legacy agent. They sit in the agent type's settings section of the legacy agent form — Windows settings, Unix settings and so on — on both New Agent and an existing agent's dialog.
| Setting | Shown on | Default | What it does |
|---|---|---|---|
| Check CRC | Every legacy agent type: Windows, Unix, IBM i, MCP, SAP R/3 and CRM, z/OS, SQL, SAP BW, OS 2200 and BIS | On | Turn off only for agents that do not send a CRC. Messages that fail the check are discarded. While it is on, the relay checks the CRC on the messages the agent sends. Turn it off for an agent whose messages carry no CRC, so they are not thrown away. |
| Requires XML Escape Sequences | Windows, SQL and MCP only | On for Windows and SQL, Off for MCP | Escapes reserved XML characters in job details sent to this agent. On, the job's values are sent with quotes, ampersands and angle brackets converted to XML entities, which the agent converts back. Off, they are sent exactly as typed. |
No other agent type, and no OpCon MFT, OpCon RPA, EASE or Universal Agent, shows either switch, and the platform refuses them on any other type. A switch left at its default stores nothing, so the agent keeps following the default.
When a change applies. The section says so under its heading:
- Check CRC — Changes to Check CRC are sent to the agent when you save. If the agent is connected, its connection is re-established automatically. On an SAP R/3 and CRM agent the line reads Changes to Check CRC, SAP events to monitor are sent…, because both reconnect.
- Requires XML Escape Sequences — Changes apply to jobs started after you save. There is no reconnect: the relay picks the change up at its next check-in, and a job already started keeps the way it was sent.
Both need a current relay.
- Saving a changed Check CRC behind a relay that has not reported it can apply the setting is
refused: Relay
<name>has not reported support for the Check CRC setting. Upgrade the relay. - An agent whose Requires XML Escape Sequences differs from its type's default can still be saved, but its jobs, SMAFT transfers included, are refused behind such a relay. They go to Initialization Error with RELAY_LSAM_FEATURE_UNSUPPORTED: relay '…' (agent pool '…') has not reported support for the Requires XML Escape Sequences agent setting on … jobs. Upgrade the relay, or reset the agent's Requires XML Escape Sequences to its default.
- An agent left at its defaults runs on any relay.
Two character sequences are never sent unescaped. With Requires XML Escape Sequences off, a
job value that contains </F> or <F I= is refused at dispatch, naming the field, and the job fails
without running, as on UNIX — see
UNIX values reach the agent exactly as you typed them.
Service and Status
Taking an agent out of service
An agent's Status reports what the platform observes — whether the machine is reachable and answering. That is not the same question as whether you want work to go there. Patching a host, draining it before a reboot, or holding a misbehaving machine back are all decisions the platform cannot infer from a heartbeat.
So an agent carries a second, separate value: its operator state. You set it and you clear it,
and a heartbeat never overwrites it. A $MACHINE:STATUS event can also set it, whether a machine
raises it — see Events raised by a legacy agent — or a person or a job sends
it — see Machine events. Marking an agent that later reconnects leaves it marked.
| Action | Operator state | What it does |
|---|---|---|
| Mark Offline | Marked Offline | Stops communication with the agent: its connection is closed, no work is sent to it, and it is not selected as a pool or group member. See What Mark Offline does to communication. On an OpCon MFT, OpCon RPA or EASE agent, which has no connection to close, it treats the agent as out of service without stopping anything. |
| Mark Draining | Marked Draining | Stops new work reaching the agent. Communication continues, and jobs already running finish normally. Use before planned maintenance. |
| Clear Mark | Active | Returns the agent to service. If communication was stopped, a new connection is opened. Its status reverts to observed connectivity. |
Where to find them. Each agent's row menu on the Agents tab — Universal and legacy agents alike. All three actions are always listed; the ones that would not change anything for the agent's current state are shown disabled rather than hidden.
A Reason is optional and, when supplied, is stored with the mark and shown in the status tooltip alongside who set it and when. If the agent is currently running jobs, the confirmation warns you and tells you how many — it warns, it does not block, because draining a host for maintenance is exactly the case where work is still on it. For Mark Offline it reads … job(s) are running on this agent. They keep running, and their results are collected when communication resumes.; for Mark Draining, and for Mark Offline on an OpCon MFT, OpCon RPA or EASE agent, … They will finish normally; no new work will be sent.
Who set it. The tooltip's Set by line, and Changed By in the Audit History report, name whoever made the change:
| How the mark was set | Recorded as |
|---|---|
| Mark Offline, Mark Draining or Clear Mark on the Agents tab | You: your email in Set by, your name in Audit History |
A $MACHINE:STATUS event a signed-in person sent, through a Self Service button or the events API | That person, by name |
A $MACHINE:STATUS event a job, a workflow, a notification, a Vision trigger or the machine itself raised | The platform: Set by system, and System in Audit History |
What a mark changes
An agent is eligible for new work only when it is observed Online and its operator state is Active. Everything below follows from that one rule.
- Nothing new is dispatched. A marked agent is skipped when a pool or a legacy group picks a target, and the paths that hand work to an agent after selection are blocked too.
- Running jobs are left alone. A mark stops the next job; it never interrupts one already underway.
- A job targeting a marked agent holds. It waits in Waiting: Machine rather than failing, and proceeds once the mark is cleared. Your intent is trusted whether or not the relay feed is fresh.
- A fully drained legacy group defers rather than fails. When a group's jobs could have dispatched but for the marks, they hold in Waiting: Machine instead of dying with Initialization Error and releasing their dependents as failures. Marks are no longer the only case that holds — see When a legacy group has no dispatch target.
- Force start is refused. Force-starting a job onto a marked agent is rejected with an error naming the agent, its mark and the reason recorded on it. Onto a legacy group with no unmarked member available, it is rejected with Cannot force-start: no unmarked member of the target legacy agent group is available. Clear a mark to proceed. There is no override; clear the mark instead.
- Pool counts follow. The Online count on the Agent Pools tab means dispatchable — for a Universal Agent pool and a legacy agent group alike — so a drained pool no longer reads as fully online while accepting no work.
A mark applies to work already being polled for within about five seconds, not instantly. Clearing one takes effect on the same window. A job dispatched in that gap runs normally.
What Mark Offline does to communication
Mark Offline stops all communication with a legacy agent or a Universal Agent until you clear it. Mark Draining never does: an agent marked Draining stays connected, and moving between Active and Marked Draining never touches its connection.
A legacy agent is disconnected. At its next check-in, within about a minute, the relay closes its
connection to the agent and does not open another while the mark stays — not after a relay restart,
and not after a standby takes over. The agent reads Offline underneath the mark, so another
scheduler can connect to the machine in the meantime. A mark set by a $MACHINE:STATUS event works
the same way.
While the agent is Marked Offline:
- No job start reaches it. A start the relay was still holding for the agent when you marked it is withdrawn, and the job fails with Agent '…' is marked offline. The job was not sent., rather than going out later.
- Jobs already running keep running on the machine. Their results are collected once communication resumes, and a job is never failed or given up because of the mark: the relay's seven-day wait for a disconnected agent does not run out while the mark lasts, and starts again from the clear.
- A Kill is held. It is accepted — the job shows Running (To Be Terminated) — and is sent to the agent after you clear the mark.
- Requests to the agent are refused, each with its own message: a job's output — Job output is not available: agent '…' is marked offline. — the SAP lookups and Check SAP Job Numbers (LSAM query is not available: …), and viewing or saving z/OS JCL (JCL is not available: …).
- No Offline or Online notification is raised for it — see Triggers.
Clear Mark opens a brand-new connection. Clearing the mark, or changing it to Mark Draining, has the relay open a new connection to the agent at its next check-in, so Mark Offline followed by Clear Mark resets one agent's connection without touching the other agents on the relay. Until the agent reports back, a job aimed at it waits in Waiting: Machine. Anything that was waiting inside the relay for the machine while it was stopped is discarded, not sent in a burst, and held kills are then delivered.
A Universal Agent is refused. While it is marked, a Universal Agent stops asking for work and checks back on a lengthening interval, up to every two minutes, then resumes on its own once you clear the mark. Jobs it was already running keep running and report their results, and they are not shown as Lost in Failover while the mark lasts.
When communication cannot be stopped. An older relay, or an older Universal Agent, does not know how to stop communication. Mark Offline is still accepted and still holds new work, but a warning icon beside the status, and its tooltip, say so:
| Warning | Cause | Do this |
|---|---|---|
| Communication is not stopped. Upgrade the relay to stop communication with this agent. | A running instance of the agent's relay has not reported that it can stop communication | Upgrade every instance of the relay — see Keeping a relay current |
| Communication is not stopped. Upgrade the agent to stop its communication. | The Universal Agent is still checking in normally after the mark | Update the agent |
The Last Heartbeat then keeps showing the time, because the agent is still checking in.
OpCon MFT, OpCon RPA and EASE agents have no connection to close. Mark Offline on one holds new work, as it always has, and a Kill on one of its jobs is sent as usual.
How a marked agent is displayed
The status chip shows the mark, not the observed status. Marked Offline always reads alone,
because the mark stops communication. Marked Draining is composed with the observed status when
the two disagree — a drained agent that is still reachable reads Marked Draining, while one that
has since gone down reads Offline (Marked Draining). Hovering shows the reason, who set the mark,
and when, led by the warning when communication could not be
stopped.
Filtering:
- The Status filter on the Agents tab matches what the chip shows: any of Online, Offline, Unknown, Marked Draining and Marked Offline. A marked agent matches its mark only, so Online lists agents that are online and unmarked.
- In the Agents report, Status keeps its observed-only meaning, and a Marked Draining agent is usually still connected, so it does match Status is Online there. To report on agents that can actually take work, filter on Operator State as well — see Reports.
Marks also reach the rest of the product: the Agents dashboard widget counts them as their own slices rather than folding them into Online, the Agents report can show and filter on them (see Reports), and they can raise a notification (see Notifications).
How quickly a stop is noticed
There are two ways an agent or relay can stop, and they are detected by completely different mechanisms — which is why one shows up almost immediately and the other takes a while.
A clean stop announces itself. A Universal Agent or a relay shut down normally reports itself offline as the first thing it does on the way down. That takes about a second: you can stop an agent and see it offline on the next refresh of the page.
An abrupt loss has to be inferred. If the process is killed, the host loses power, or the network drops, nothing announces anything. The platform notices only when heartbeats stop arriving, which takes:
| What was lost | Noticed after roughly | Result |
|---|---|---|
| A Universal Agent | 90 seconds — three heartbeat intervals at the default 30 seconds | The agent goes Offline |
| A relay | 2 minutes — four heartbeat intervals at the default 30 seconds | The relay goes offline and its legacy agents go Unknown |
| A relay that does not come back | An hour without a heartbeat | Its Unknown legacy agents go Offline, with no notification for each. When the relay returns, each agent that is still down raises one Agent Offline. Earlier builds left the agents Unknown for as long as the relay was gone |
Two minutes is a deliberate debounce, not an oversight. A shorter window would turn a brief network blip into Unknown legacy agents across the relay, and every queued legacy-group job holding through it for nothing. The clean-stop signal means a real relay shutdown is still reflected in seconds; the long window only applies when the relay vanishes without warning.
A Universal Agent's work is not left with it. When a Universal Agent goes Offline this way, work it had taken in the last 11½ minutes or so and not started goes back on its queue to be picked up again, and work it was running is shown as Lost in Failover once it has been silent for about 10 minutes more — see When a Universal Agent stops responding. A job whose work no agent picks up at all is ended rather than left Running — see A job no agent picks up is ended.
Either way, queued legacy-group work waits. The two paths leave the relay's legacy agents in different states, and the difference is now only how fast it is noticed:
- Clean relay stop → its legacy agents go Offline, about a second later. A legacy-group job holds in Waiting: Machine until the relay reports in again.
- Abrupt relay loss → its legacy agents go Unknown after about two minutes. A legacy-group job holds too, and resumes when the relay reconnects.
An abrupt loss used to be the worse of the two by far: the Waiting: Machine gate failed open on an Unknown feed, the job advanced, and a least-tasked group with no online member then failed at dispatch — No ONLINE legacy-group member with a dispatch pool for job … — releasing its dependents as failures. Stopping a relay cleanly is still worth doing, because a clean stop is reflected in seconds rather than two minutes, but it is no longer the difference between work waiting and work being destroyed.
Status lists refresh every 10 seconds while you have them open, so you do not have to reload the page to watch an agent come back.
After the platform itself restarts, it waits before judging anything stale — long enough to give every agent and relay a chance to check in. Nothing is marked offline just because the platform was the thing that was down.
Job Routing
How jobs are routed to agents
A job's agent assignment (set in the workflow) carries a kind (agent-pool or
legacy-group) and a mode:
| Assignment | Mode | Behavior |
|---|---|---|
| Specific agent | — | The primary agent, or, when the primary cannot take the job, its first available backup agent. For a Universal Agent, see the note below. |
| Agent pool | least-tasked | One job placed on the pool's queue, run by whichever agent in the pool asks for work first. No agent is chosen by load. |
| Agent pool | run-all | The same as least-tasked: one job on the pool's queue, run by one agent. A Universal Agent pool job does not fan out to every agent. |
| Legacy agent group | least-tasked | An Online, unmarked member of the group, picked at random — not by load. |
| Legacy agent group | run-on-all | Every member — fanned into one job instance per member, frozen at build. |
Which assignments a job type allows
Most job types allow every assignment above, and backup agents. Two run on one specific agent only, with no backup agents:
| Job type | Why |
|---|---|
| SMAFT File Transfer | A file transfer runs on the machine that Start Transfer On selects. |
| OpCon RPA Task | An RPA task belongs to one RPA agent. |
The job editor offers only what the job type allows: on these two, the pool and group choices are marked Not available for this job type. and there is no Configure backup agents switch. A save that sets a disallowed assignment anyway — from the workflow, an import, a job-instance edit or an added job — is refused, naming the job: RPA job '…': an RPA task belongs to one RPA agent, so this job runs on one specific agent. Choose a specific agent. (or … Remove the Secondary Agent.). Changing a job's type to one of these two is checked against the assignment it keeps.
A job saved with one of these assignments before the rule existed keeps it, and stays editable: the editor shows This job type does not support this agent assignment., and the save is refused only when you change that job's assignment or type. Choose Specific Agent and remove the backup agents to clear it.
The platform does not pick a Universal Agent for a job. It puts the job on the queue of the job's pool, and the first agent in that pool to poll takes it. That is also true of a job assigned to a specific Universal Agent: it goes on the queue of that agent's pool, so any agent in the same pool can run it. To pin work to one machine, give that agent a pool of its own.
Backup agents
A Specific Agent job can name up to three backup agents: in the job editor, turn on Configure backup agents and choose a Secondary Agent, Tertiary Agent and Quaternary Agent, in that order (a tertiary agent needs a secondary one, and a quaternary one a tertiary one). When the job is ready to start and its primary agent cannot take it, the job runs on the first backup, in that order, that can.
| What | How it works |
|---|---|
| When a backup is used | Only when the primary is not available: not Online, Marked Offline or Marked Draining, a legacy agent whose relay has not reported it for more than five minutes, or not known to the platform. While the primary is available, the job runs on it and the backups are never looked at |
| Which backup | The first one, in order, that is Online, not marked, reported by its relay in the last five minutes if it is a legacy agent, and has a pool the job can be sent to. The order stops at the first empty slot |
| Every run starts again from the primary | A restart, a failure retry, a recurring run and a force start each check the primary first, so the job goes back to its primary as soon as it is available |
| When none is available | The job waits in Waiting: Machine until the primary or one of its backups can take it. The agents are checked again just before the job is sent; if none can take it by then, nothing is sent, and the job goes back to Waiting: Machine (a force-started or Late to Start job stays in its status). Earlier builds then sent the job to the primary even when it was Offline or Unknown |
| If the platform cannot tell | A job is never sent on a guess. While the primary's status cannot be read, the job is not sent and is tried again on the next pass. A backup whose status cannot be read is not used, so a brief platform problem never moves your jobs onto backups |
| Which agent ran it | The run shows the backup's name as its Agent in Processes and the job's Summary, and $MACHINE NAME in the job resolves to the backup. The job's output and Kill go to that agent, and Kill follows that agent's Allow Kill setting |
| Force start | Refused for a marked primary only when no backup could take the job either. An accepted force start waits in Wait to Start (Forced) while neither the primary nor a backup can take the job, and is sent as soon as one can |
Backups are used only by a job assigned to a specific agent. A job on an agent pool or a legacy agent group, an SMAFT File Transfer or OpCon RPA Task job, and a z/OS Tracked Job or z/OS Queued Job never use them, even when backup agents are stored on the job. SMAFT and RPA jobs cannot be given backup agents at all — see Which assignments a job type allows. A Universal Agent backup is reached through its pool, so any agent in that pool can take the job.
A backup is not checked for the job's type before the job is sent to it: choose backups that can run the job, because a backup that cannot is refused the job exactly as the primary would be. The one check made is for OpCon MFT, OpCon RPA and EASE jobs: a backup whose relay has that kind of job turned off is skipped, as an unavailable one is. The primary is never skipped for it.
A pool job records which agent actually ran it. Because the pool decides at claim time, the agent is not known until the run is over — so a least-tasked pool job's Agent shows the pool while it is queued and running, and is replaced by the agent that ran it when the run completes. That is what makes a completed pool job traceable to a machine.
Two limits worth knowing:
- It is the current attempt's agent, not a history. The name is cleared when a new attempt starts, so a retried or recurring job shows the pool again until that attempt completes. The previous attempt's agent is not kept on the job.
- A pool set to run-all does not record it, and neither does a job that ends without ever being claimed — an unclaimed job, or one cancelled or marked while it waited. Those keep showing the pool.
Legacy LSAM job types dispatch through a legacy agent group (or a specific legacy agent), not a Universal-Agent pool — the assignment selector only offers groups compatible with the job type, and a group holds agents of a single type. See Job configuration. Whichever route a job takes, the assignment selector offers only the agents, pools and groups whose type/OS match the job type's requirements. For a Universal Agent pool that means the pool holds at least one such agent; the job is still taken by whichever agent in the pool polls first.
A legacy job aimed at an agent of another type
A legacy job is sent to the agent its machine name points at, and each legacy job type is built for one platform. A job whose machine name points at an agent of a different type is refused when it is dispatched, rather than sent: a UNIX Command job aimed at a Windows agent, for example. This can happen when a deployment transformation, a hand edit, or an agent deleted and re-created under the same name with another type leaves the job pointing at the wrong kind of machine. The job ends in Initialization Error and its Termination names both types:
LSAM_AGENT_TYPE_MISMATCH: this job needs an agent of type Unix, but agent '…' on relay '…' has type Windows. Point the job at an agent of type Unix.
Point the job at an agent of the type the message names. A SMAFT File Transfer job is not affected: its platform is taken from the machine it starts on. If no agent with that name is registered under the relay, the job is not refused here; it fails as it always has, on the missing connection.
Group dispatch gating. A least-tasked group job advances only when the group has a member dispatch could actually route to: one that is observed Online, unmarked, and has a resolved relay dispatch pool. The gate applies the same test dispatch does, so the two can never disagree — which is what stopped a job passing the gate and then dying at dispatch. Otherwise the job holds in Waiting: Machine, and an Unknown relay feed holds it too, as it does a specific-agent job. A job also holds while the group's members cannot be read. Earlier builds let the job through in that case.
A run-on-all group job resolves its members to a frozen snapshot at build and reuses the multi-instance loop (one instance per member); its children are pinned to a member and take the specific-agent gating above.
When a legacy group has no dispatch target
A least-tasked group job is released from Waiting: Machine only when the group has a member dispatch can route to, so in every one of these cases the job holds and starts on its own once the group has one:
| The group | What happens |
|---|---|
| Has no members | Holds — a member may still be added |
| Has members, all observed Unknown (its relay was lost abruptly) | Holds — status will come back when the relay does. After the relay has been gone for an hour its agents read Offline, and the row below applies |
| Has an Online, unmarked member whose relay dispatch pool is not resolved yet | Holds — the pool resolves on its own |
| Is blocked only because its members are marked | Holds until a mark is cleared |
| Has members that are all observed Offline, with no mark | Holds until a member comes back online |
| Has usable members, but none of them on a relay that has reported it can run the job's platform | Holds until such a member is available — see Relays: serving legacy LSAM agents |
| Has usable members for an OpCon MFT, OpCon RPA or EASE job, but every one is on a relay with that kind of job turned off | Holds until a member on a relay that runs it is available. A least-tasked job never goes to a member whose relay has it off |
A job holding this way is tracked as a long hold like any other, so it shows up as waiting rather than disappearing.
An all-Offline group fails a job with Initialization Error — No ONLINE legacy-group member with a dispatch pool for job … — in only two situations: the job was force-started, which skips the Waiting: Machine gate, or the group's last usable member went offline or was marked in the moment between the gate releasing the job and dispatch.
Force start is refused for every case except an all-Offline group. Force start bypasses Waiting: Machine gating, so permitting it left the forced job deferring silently at the dispatcher with nothing to say why. It is now rejected up front with the reason:
| The group | The refusal says |
|---|---|
| No members | the target legacy agent group has no members. Add a member to proceed. |
| All Unknown | every member of the target legacy agent group has UNKNOWN status (relay unreachable). Wait for the relay to reconnect. |
| No member with a dispatch pool | no ONLINE member of the target legacy agent group has a dispatch pool. |
| Blocked only by marks | no unmarked member of the target legacy agent group is available. Clear a mark to proceed. |
| No usable member on a relay that runs the job's platform | Cannot force-start: no available member of the target legacy agent group is on a relay that supports Unix jobs. Bring such a member online, or upgrade a member's relay. (naming the job's platform; for an OpCon MFT, OpCon RPA or EASE job it reads … supports these jobs …) |
Force-starting onto an all-Offline group is allowed, and fails the job at dispatch with Initialization Error.
- Heartbeat "Never" on a legacy agent means its relay hasn't reported it yet — a common first thing to check when a legacy job finds no agent to run on. On a Universal Agent it means the agent program has not checked in since the agent was registered: a new Universal Agent reads Offline until it does.
- To take an agent out of service, use the operator mark (Mark Draining or Mark Offline). The observed Draining and Busy statuses are never set in this build, and there is no observed disabled state — Disabled was removed from the status list because nothing ever set it.
- Unknown vs Offline for legacy agents: Unknown (yellow) means the relay is stale, so a legacy LSAM agent's reachability can't be confirmed — not that the agent is down. Offline means the agent itself is down. Either way, a job aimed at the agent holds in Waiting: Machine. When a relay recovers, its agents leave Unknown on the next heartbeat. A relay gone for an hour leaves its agents Offline instead of Unknown. How fast a stop is noticed depends on how it stopped — see How quickly a stop is noticed.
- Legacy agents and groups are managed in-product: legacy agents on the Agents tab alongside Universal Agents, and legacy agent groups on the Agent Pools tab. Register, edit or delete a legacy agent there; the relay hot-reconciles its LSAM connections within one heartbeat — no relay restart needed. Agent names are unique per relay, and a legacy agent's name must be 128 characters or fewer: the platform accepts up to 255, but the relay refuses to connect to an agent with a longer name, so it never comes online.
- Legacy agent groups are type-homogeneous (all members share one legacy type) and may span relays. A group is an operational dispatch target for a legacy job (least-tasked or run-on-all; see the routing table). A group can be deleted only once it has no members, and deleting it never deletes the agents that were in it.
- A Universal Agent's CPU, memory, disk and installed plugins are not displayed — the
--on its Edit Agent dialog is expected, not a fault on the agent.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job can't be assigned / Waiting: Machine | No matching agent Online (type/OS mismatch, all offline, or every candidate marked) | Check agent status/type vs the job's requirements (Administrator). |
| Specific-agent job sits in Waiting: Machine | The job targets one specific agent that cannot take it — Offline, Unknown (its relay was lost), marked, deleted, or a legacy agent its relay has not reported for more than five minutes — or the agent's status cannot be checked. It holds rather than fail, and proceeds when the agent can take it. The job's Status History has an Agent Availability Hold entry that says which | Bring the target agent online, or reassign the job (Administrator/Builder). |
| A job sits in Waiting: Machine although its legacy agent reads Online | The agent's relay is running but has not reported the agent for more than five minutes; its Last Heartbeat shows how long ago it last did | Check the relay and its connection to the machine (Administrator). |
| A Universal Agent pool job sits in Waiting: Machine | The pool has agents, and none of them is Online and unmarked | Bring an agent in the pool online, or clear a mark (Administrator). |
| A job assigned to one Universal Agent ran on a different one | The job went on the queue of that agent's pool, and another agent in the pool took it first | Give the agent a pool of its own if the work must run there (Administrator/Builder). |
| A run-all pool job ran on only one agent | A Universal Agent pool job is one job on the pool's queue, whichever mode is set | Add one job per agent, each assigned to an agent in its own pool (Builder). |
| A new Universal Agent never comes online | It was never registered through the API, or its credentials file is missing or has extra keys — the install commands in New Agent do not register it | Register it and write its credentials file — see Registering a Universal Agent (Administrator). |
| Least-tasked group job sits in Waiting: Machine | The group has no member dispatch could route to — none Online and unmarked with a resolved dispatch pool. It holds and proceeds when one appears. An all-Offline, all-Unknown (relay-lost) or empty group holds here too, rather than failing | Bring a group member online, or check the relay — see When a legacy group has no dispatch target (Administrator). |
| A legacy job fails with Initialization Error and LSAM_AGENT_TYPE_MISMATCH: this job needs an agent of type … | Its machine name points at an agent of another type — for example a UNIX job aimed at a Windows agent | Point the job at an agent of the type the message names — see A legacy job aimed at an agent of another type (Builder). |
| A save is refused with SMAFT job '…' or RPA job '…', saying the job must run on one specific agent or machine | The job is set to a pool, a group or backup agents, which its type does not allow | Choose Specific Agent and remove the backup agents (Builder). See Which assignments a job type allows. |
| Least-tasked group job fails with Initialization Error | It was force-started onto a group with no member online, or the group's last usable member dropped in the moment between the gate releasing the job and dispatch | Bring a member online and add the job again (Operator/Administrator). |
| Creating or renaming a z/OS agent is refused with z/OS agent names must be at most 8 characters | The name is longer than 8 characters | Use a name of up to 8 characters; it is saved in upper case — see z/OS agent names (Administrator). |
| A new z/OS agent clashes with an existing agent whose name differs only in case | A z/OS name is upper-cased before it is compared, so zprod1 and ZPROD1 are the same name | Choose another name (Administrator). |
| Creating or renaming an MCP agent is refused with MCP agent names must end with a period (.) and be at most 24 characters | The name has no trailing ., or is longer than 24 characters | Use a name such as MCPPROD. — see MCP agent names (Administrator). |
| Every OS 2200 Job fails with Initialization Error and RELAY_LSAM_FEATURE_UNSUPPORTED: … the XML job start format on OS 2200 jobs | The agent's Job Start Format is XML — the default — and its relay has not reported it can send XML | Upgrade the relay, or set the agent's Job Start Format to Non-XML — see OS 2200 Job Start Format (Administrator). |
| Saving a BIS agent through the API is refused with jorsPort cannot be set on BIS agents: they have no JORS listener | The request carries a JORS port, which a BIS agent cannot have | Leave the JORS port out (Administrator). |
| Agent shows Offline / heartbeat stale | Connectivity or the agent process is down | Check the agent host and network (Administrator). |
| Agent looks healthy but takes no work | It's marked — the chip reads Marked Offline or Marked Draining. A mark survives a reconnect, so one set during past maintenance is still in force. | Hover the chip for the reason and who set it, then Clear Mark (Administrator). |
| A Marked Offline agent's status shows a warning icon: Communication is not stopped. Upgrade the relay … or … Upgrade the agent … | The relay, or the Universal Agent, is too old to stop communication. New work is still held | Upgrade the relay or the agent — see What Mark Offline does to communication (Administrator). |
| A legacy job fails with Agent '…' is marked offline. The job was not sent. | The agent was marked Offline while the job's start was on its way, so the start was withdrawn rather than sent later | Clear the mark, then run the job again (Operator/Administrator). |
| A job's output, an SAP lookup or z/OS JCL is refused with … is not available: agent '…' is marked offline. | Mark Offline has stopped communication with the agent | Clear the mark, then try again (Administrator). |
| Saving a legacy agent is refused with Relay … has not reported support for the Check CRC setting. Upgrade the relay. | Check CRC was changed on an agent whose relay cannot apply it | Upgrade the relay, or leave Check CRC as it was — see Check CRC and Requires XML Escape Sequences (Administrator). |
| A Windows, SQL or MCP job fails with Initialization Error and RELAY_LSAM_FEATURE_UNSUPPORTED: … the Requires XML Escape Sequences agent setting … | The agent's Requires XML Escape Sequences differs from its type's default, and its relay has not reported it can apply it | Upgrade the relay, or reset the setting to its default (Administrator). |
| Force start rejected, naming the agent | The target agent is marked | Clear the mark, or retarget the job. There is no force-start override (Operator/Administrator). |
| Force start rejected with no unmarked member of the target legacy agent group is available | Every usable member of the target legacy group is marked | Clear the mark, or retarget the job. There is no force-start override (Operator/Administrator). |
| Force start rejected, naming the legacy group | The group is empty, entirely Unknown, or has no Online member with a dispatch pool. The refusal names which | Fix what it names — add a member, wait for the relay — then force start again (Operator/Administrator). |
| Deleting an agent opens "…" is in use, so it cannot be deleted yet., or a delete of several names it as still online or in use by … | The agent is online, has jobs waiting or running on it, or a workflow or an unfinished job names it — see An agent in use cannot be deleted | Mark Offline the agent, let its jobs finish, and remove it from the jobs the dialog lists, then delete it again (Administrator). |
| Deleting an agent is refused with The delete could not be checked: … | An environment, the workflow lookup or the environment list did not answer, or your roles do not grant Job Instances View in every workspace of the environment it names | Try again later, or ask an administrator whose roles grant Job Instances View in every workspace to delete it (Administrator). |
| A pool's Delete is disabled, or the delete is refused with … has N agent(s); remove them first | The pool or legacy group still has agents | Remove or delete its agents in Edit Agent Pool, then delete it (Administrator). |
| Remove from Pool is disabled on a Universal Agent | A Universal Agent always has a pool, so removing one moves it to the default-cloud pool — and there is no pool by that name | Add the agent to another pool instead, which moves it there, or create a pool named default-cloud (Administrator). |
| A Universal Agent added to another pool still runs the old pool's work | The move takes effect at the agent's next sign-in refresh, up to about 15 minutes later | Wait for the refresh, or restart the agent (Administrator). |
| Pool reads fewer online than you expect | Pool online counts only agents that can actually take work, so marked members are excluded | Check the pool's agents for marks (Administrator). |
| Legacy agent shows Unknown (yellow) | Its relay is stale/down — agent reachability can't be determined (not the same as the agent being down) | Check the relay; on recovery, agents leave Unknown within a heartbeat (Administrator). |
| Jobs pile up on one Universal Agent | The agent's concurrency cap is reached. On a Universal Agent the cap is its MAX_CONCURRENT_JOBS setting, not the value on its row. A legacy agent's Concurrent Jobs (max) is not a limit, so it is not what holds a legacy agent's jobs back | On a Universal Agent, raise MAX_CONCURRENT_JOBS in the agent's environment and restart it, or add agents to the pool (Administrator). |
| A Universal Agent with free slots takes no new work | It is still running a job from its last batch, and it does not poll again until the whole batch has finished | Expected in this build. Keep long-running jobs on agents of their own (Administrator / Builder). |
| A Universal Agent job fails after exactly one hour | Every Universal Agent job has a fixed one-hour limit | Split the work so each job finishes within the hour (Builder). |
| Kill on a legacy job is refused with Cannot kill: agent '…' does not allow its jobs to be killed | The agent's Allow Kill is off — the default on an SAP R/3 and CRM agent | Turn on Allow Kill for the agent if its jobs should be killable — see Allow Kill (Administrator). |
| Kill is refused with Cannot kill: jobs on … agents cannot be killed | The agent is an SAP BW, OS 2200 or BIS agent, whose jobs can never be killed | Let the job end on its own, or stop it on the machine (Administrator). |
| Kill is refused with Cannot kill: the agent's kill setting could not be checked … | Continuum could not read the agent's setting just then | Try again; nothing about the job was changed (Operator). |
| A tab of the Agents page is missing, or the page reads You do not have permission to view agents, agent pools or relays | Your roles do not grant that tab's View permission under All workspaces; a grant confined to particular workspaces does not count | Grant Agents View, Agent Pools View or Relays View under All workspaces — see Agents, agent pools and relays are checked (Administrator). |
| New Agent, Delete or another action is unavailable, with You do not have permission to … | Your roles do not grant that action's permission under All workspaces | Grant the permission the tooltip names (Administrator). |
| Kill on a Universal Agent job doesn't stop it | Kill reaches legacy agents only | The job ends when its process ends, or at the one-hour limit. Stop the process on the agent machine if it must end sooner (Administrator). |