Events raised by a legacy agent
This feature is still being finalized by Development.
- Synopsis
- Full Details
In briefA job or process on a legacy LSAM machine can raise a Continuum event by writing a file of event syntax into the agent's MSGIN directory. The agent sends each line through its relay; Continuum verifies the line's trailing credential pair, checks the service account's roles, and applies the event to the machine's Default event environment. It needs no inbound network path to the platform, and nothing on the machine holds an interactive sign-in.
WhereOn the platform, the Default event environment is set on the New Agent or
Edit Agent dialog on the Agents tab of the Agents area. The warning that counts agents
without one, with its Assign environment… action, is on the same tab. On the machine, events
are raised by writing a file into the legacy agent's MSGIN directory. What happened to each
event is in the event log, filtered to source AGENT; a line refused at the
platform edge is not there.
WhenUse this channel when:
- a script or job on a legacy LSAM machine has to raise an event — add a job, build a schedule, set a property, take its own machine out of service, send mail;
- you are moving existing event files onto Continuum, and need the credential they carry to keep working;
- a machine's event file produced nothing, or the event applied somewhere unexpected;
- a z/OS agent tracks or queues jobs, and you need to know what its reports do and why one was refused.
A Universal Agent has no MSGIN directory, so this channel does not apply to it.
How
- Set the agent's Default event environment.
- Create an event identity on Administration › Permissions › Event Identities, named for the login ID the event files carry, with only the roles those events need.
- Put the identity's secret in the emitter's configuration as the token.
- Write each line as
$TYPE:ACTION,<values>,<login ID>,<token>, in plain ASCII with a leading$. - Confirm the outcome in the event log, filtered to source
AGENT.
For the steps on the agent, see Set each legacy agent's default event environment.
- An unset Default event environment refuses every event from that machine, and there is no per-event override.
- Every event family is admitted, but some types are recorded as
FAILEDbecause the platform does not carry them out, among them$MACHINE:MAXJOBSand eight$NOTIFYtypes. - A line can reach global properties and the clock, not job-, schedule- or machine-scoped tokens.
- A
$PROPERTYline with anMI.name writes a machine property: the sending machine's when the machine part is blank, or the agent it names. - A
$JOB:ADDwith properties for a multi-instance job always adds an ad-hoc instance namedAdHoc, because a value from a machine is never used as a name. - A z/OS agent's
$JOB:TRACK,$JOB:QUEUEDand$JOB:QUESTATElines land only on that machine's own z/OS Tracked and Queued jobs, and a refused Track or Queue line is answered to the agent.
- Delivery is at most once: the agent deletes the file before Continuum acknowledges it, so a lost or refused line must be raised again.
- A line refused at the platform edge (bad credential, missing permission, wrong field count, unset environment) leaves no trace in the event log.
- One line over 4,096 bytes loses its whole relay batch, including other machines' events.
- The
SYSTEM/MESSAGEpair is admitted unverified for eleven types, one of which sends mail; restrict write access to MSGIN. Its three job types reach only the machine's own Tracked and Queued jobs.
See Relays, Agents and agent pools and Event log.
A job — or any process — running on a legacy LSAM machine can raise an OpCon Continuum event without an inbound network path to the platform. It writes a file of OpCon event syntax into the agent's MSGIN directory; the agent picks the file up, sends each line to Continuum over the connection it already holds open through its relay, and Continuum applies it.
Each line carries its own credential pair, which Continuum verifies and then checks against that service account's roles — so the machine needs a credential for this channel, but nothing on it holds an interactive Continuum sign-in.
The agent side of this already ships in every installed Windows and UNIX/Linux LSAM. Nothing on the machine has to change, and existing event files in the comma-separated event syntax carry over unmodified. A line written in the XML event syntax is not accepted from MSGIN: it is not applied as an event.
This applies only to legacy agents reached through a relay. Universal agents have no MSGIN directory, and the setting described on the Default Event Environment tab is not offered for them.
- Default Event Environment
- Writing a Line
- Applied Events
- Records and Rejections
- Delivery and Platforms
- Troubleshooting
Default Event Environment
Before any event can be applied: Default event environment
Every event raised this way is applied to one environment, named on the agent's own registration.
| About the setting | How it works |
|---|---|
| Where | The New Agent or Edit Agent dialog on the Agents tab of the Agents area, for a legacy agent |
| Field | Default event environment — a list of the tenant's environments |
| At registration | Required for every agent type that raises events — every legacy LSAM type and EASE. OpCon MFT and OpCon RPA agents have no MSGIN directory, so the field is optional for them |
| Unset | Every event that machine raises is refused. There is no fallback to "the only environment" or "the first environment" |
| Clearing it | Still allowed when you edit an agent. It clears the setting back to unset, which stops every event that machine raises |
| What is accepted | Only an environment that exists and belongs to your tenant. A typo, a deleted environment or another tenant's identifier is refused when you enter it |
An unset Default event environment refuses events uniformly — not just the ones that address a schedule or a job. The machine has already deleted the event file by the time Continuum sees the line, so a refused event cannot be recovered by retrying: the process has to raise it again.
A new agent cannot be registered without one
Registering an event-raising legacy agent now requires the environment. It used to be optional, which made it possible to register a machine into a state where every event it ever raised was rejected — and the only trace was a line in the relay's log, long after the fact, with the event file already deleted by the agent.
The value is also checked at the point of entry now, on registration and on every edit: a
non-empty value has to name an environment that exists in your tenant, or the save is refused with a
message on the field. Before, a mistyped or stale identifier was stored as given and only surfaced
much later — and not always as a clear failure, because a tenant-wide event type such as
$PROPERTY was applied with the bad identifier recorded on it.
The check runs when the value is written, so deleting an environment that agents already point at is not caught there. Those agents keep the deleted environment as their setting, are not counted as unset, and their events are still sent to it. Re-point the agents before retiring an environment.
Finding and fixing the agents that have none
While any legacy agent in the tenant is unset, the Agents tab shows a warning that counts them — "3 classic agents have no default event environment", with Every event they raise is rejected until one is set — across the whole tenant, whatever the table is filtered to. It offers Assign environment…, which sets one environment on every unset agent in the tenant at once, so a backlog of agents registered before the field existed can be cleared in a single confirmation. To check one agent, open it with Edit Agent and look at its Default event environment.
It only fills agents that are still unset when you confirm, so an agent somebody set in the meantime is never overwritten, and an agent that already has a different environment is left alone. To move an agent that already has one, edit that agent.
One machine resolves to one environment, and there is no per-event override. A machine that is shared across environments still sends everything to its configured default. The environment cannot be carried in the event text instead, because an event line names a schedule, not an environment, and the same schedule name legitimately exists in more than one environment.
The environment is read from the agent's registration on the platform side, so it cannot be overridden by anything the machine sends.
Writing a Line
What a line has to look like
Continuum treats an inbound line as an event when it starts with $ or #, followed by a name, a
colon, a second name, and then a comma — for example:
$JOB:ADD,CURRENT,DAILY,MYJOB,Mon-Fri,opconuser,mytoken
$PROPERTY:ADD,DISK_PCT_PROD01,84,opconuser,mytoken
Anything else on the connection is handled as it always was, so this cannot disturb job status or machine up/down reporting.
The trailing credential pair is mandatory, and it is now verified
Every line must end with two extra comma-separated values: a login ID and a token. This matches the legacy format, so files written for a legacy server work unchanged — and it is why a hand-authored line that omits them is refused.
The pair is checked. Earlier builds parsed it, masked it and recorded it, and then did not verify it — any machine that could write to its own MSGIN directory could raise any admitted event with no valid credential at all. Continuum now presents the pair to the Continuous identity system and rejects the line if it does not check out.
What a working credential is:
| Part of the credential | What it is |
|---|---|
| The token | A secret of one of this tenant's event identities, the service accounts Continuum keeps in the Continuous identity system. A Classic external token is not one, so it has to be replaced |
| The login ID | Must be the name of the event identity that secret belongs to, compared ignoring case. The name is what is verified against, so the login IDs already in your event files can stay as they are — you create event identities named to match |
| What is recorded | The verified account name, against the event. The token is never persisted and appears in no record you can read |
- The field count is strict and includes the pair. A line with the wrong number of values is refused rather than partly applied — including a line that ends in a stray comma, which the refusal names specifically, because a trailing separator written by the emitting script is the usual cause.
The MSGIN file format, the emitting scripts and the login ID all stay as they are. What changes is the token value in the emitter's configuration: create a service account whose name matches the login ID the file already carries, and put its secret where the old token was. Every Classic login ID carries over verbatim.
Grant that account only the roles it needs. The shipped Classic examples used an administrator login, and copying one is how a full-admin token ends up sitting in a shell script on every machine. A new credential has to be chosen anyway, so this is the moment to narrow it.
Create the account as an event identity. Go to Administration › Permissions, open the Event Identities tab and select New Event Identity. Its name is the login ID, and the secret shown when you save it is the token. See Creating an event identity.
A line whose credential verifies is then checked against that service account's roles, the way a
person's request would be. The account needs the permission the event requires, in the workspace of
the object the event names and in the machine's Default event environment — for example, a
$JOB:KILL line needs Job Instances Execute there. A line carrying
property tokens also needs permission to view every global
property it reads. A line the account may not perform is refused with EVENT_NOT_PERMITTED
before it becomes an event, so it does not appear in the event log. The
events refused for everyone stay refused whatever
the account holds.
So grant each emitter's service account only what its event files need.
An identity has no environment of its own. The same identity can be used on machines in different environments: each line is checked in, and applied to, the Default event environment of the machine that raised it. For a permission scoped by environment, such as Job Instances Execute, the identity's roles must grant it in each of those environments. See How an event identity raises events, and in which environment.
- There is no unverified mode. Every line is verified. A tenant the platform has no identity configuration for cannot have any line verified, so every line from that tenant is refused and lost — none is applied, and nothing reaches the event log.
- The literal pair
SYSTEM/MESSAGEis admitted without verification, for compatibility with a shipped legacy emitter. Lines that use it carry no account, so they are not checked against any roles either.
The SYSTEM/MESSAGE compatibility pair
One shipped Windows legacy emitter writes the literal pair SYSTEM,MESSAGE with no customer
configuration at all, and MESSAGE is not a service-account secret. So that exact pair — both
halves, matched ignoring case — is admitted without being verified, or agent notification
dispatch from that emitter would stop working on upgrade.
It is deliberately narrow:
- Only these eleven event types are admitted with it:
$CONSOLE:DISPLAY,$NOTIFY:EMAIL,$NOTIFY:LOG,$NOTIFY:NETSEND,$NOTIFY:SNMP,$NOTIFY:SPOAL,$NOTIFY:TASKSand$NOTIFY:TEXTMSG, and the three tracked and queued job events —$JOB:TRACK,$JOB:QUEUEDand$JOB:QUESTATE— which shipped z/OS LSAMs raise with this pair. Any other event type presented with this pair is rejected. - The three job events are held to the machine that raised them, whatever credential the line carries: the job must be a z/OS Tracked Job or z/OS Queued Job, and the line must name the machine it came from. So the pair cannot be used to add or start any other job.
$NOTIFY:COMMANDand$NOTIFY:SPOCOare excluded specifically, because both run something.- A line that would read a global property is rejected. The pair carries no identity a property
read could be checked against, so a line that names a global property — an
[[OI.…]]token, a system property that resolves from one, or a property name built while the line resolves — is refused. Date and time tokens such as[[$DATE]]still resolve. - The match is on the pair, so a real service account that happens to be named
SYSTEMneither gains this treatment nor is shadowed by it. The two are kept apart in the record: an event admitted this way is recorded as having used the compatibility pair and carries no verified identity.
It is open by default, for every tenant. A Continuum deployment can be set to refuse the pair's
eight notification and console events — every one of the eleven but the three tracked and queued
job events, which are never refused — with the same rejection as any other event type outside the
pair. That setting covers every tenant the deployment serves, so it is turned on only once none of
them still runs a Classic Windows emitter that sends the pair; ask your Continuous contact. While it
is open, $NOTIFY:EMAIL is in the eleven and takes a caller-supplied recipient, so anything that can write to a machine's MSGIN
directory can send mail to any address, from your tenant, without presenting a credential of its
own. Until $NOTIFY:EMAIL was implemented such a line was recorded and then failed; now it is
delivered.
$NOTIFY:TEXTMSG and $NOTIFY:TASKS also take a caller-supplied recipient, but both are now
refused outright, so neither sends anything.
Treat write access to MSGIN as sensitive on any machine you have not migrated, and restrict the directory accordingly.
The format is positional and comma-separated with no escape character, so an entity name containing a comma shifts every value after it. The field-count rule catches the cases where the total no longer adds up, but a comma inside an earlier value can still produce a line that counts correctly and means something else. Avoid commas in any name an event file refers to.
A property-token expression is the exception. Commas inside a
[[…]] or {{…}} span belong to the expression and are no longer counted as value separators, so
a line such as
$PROPERTY:SET,T,[[=Replace("a;b", ";", "-")]],opconuser,mytoken
counts as two values plus the credential pair and is accepted. It used to be refused for having too
many values, even though the same line without a credential pair was accepted elsewhere. An
unterminated [[ is still counted the old way — every comma after it separates a value — so a
span you forgot to close shows up as a field-count error rather than silently swallowing the rest of
the line.
Property tokens in an event line
A line may carry [[…]] property tokens, and they are resolved as the event is carried out — so
a script can write $SCHEDULE:BUILD,[[OI.REGION]]_DAILY,[[$DATE]],… instead of computing the
schedule name and the date in shell. Earlier builds passed the tokens through as literal text, which
was refused or applied as the characters themselves.
What a line can reach is global properties and the clock ([[$DATE]], [[$TIME]], [[$NOW]]).
A job-, schedule- or machine-scoped token has nothing to resolve against here, so the line is
refused before it becomes an event, as is a name no global property has — it does not appear in
the event log. The exception is a line that uses the
SYSTEM/MESSAGE pair: it is not checked against any
account, so its tokens are resolved only when the event is carried out, and one that cannot be
resolved fails the event in the event log.
[[…]] resolution is strict for exactly the reason the event
log is worth reading: a mistyped name that rendered as its own text would look like a
valid value and be applied.
The event type itself must be literal — a token in the first field is refused.
For the full rules, including what happens to an encrypted property and to a value that would carry a comma into the next field, see An event raised from outside a job.
Applied Events
Which events are applied
Every event family in the catalog is admitted, which matches how the channel is used today: any job on the machine can write to MSGIN, so the platform does not try to guess which families a given site needs. Three narrowings and three refusals are worth knowing:
| Rule | Effect |
|---|---|
$MACHINE:STATUS and $MACHINE:MAXJOBS may name only the originating machine | A line naming the machine itself, written exactly as its registered name, including case, is accepted; any other name is refused |
$MACHINE:* wildcards (*, ?) are refused | A single line cannot address the whole estate |
$JOB:TRACK, $JOB:QUEUED and $JOB:QUESTATE may name only the originating machine, and reach only its z/OS Tracked and Queued jobs | Any other machine or job is refused, and the agent is told Invalid Event — see Tracked and queued jobs |
$MACHINE:MAXJOBS is admitted and then fails | Continuum does not enforce a per-machine job limit, so the line is recorded as FAILED with $MACHINE:MAXJOBS is not supported yet: Continuum does not enforce a per-machine job limit, so the limit cannot be applied. Nothing changes on the agent |
Eight $JOB and $SCHEDULE types are admitted and then fail | $JOB:RESCHEDULE, $JOB:RESCHEDHLD, $JOB:USER, $JOB:MACHGRP, $SCHEDULE:START, $SCHEDULE:DELETE, $SCHEDULE:CHECK and $SCHEDULE:CHECKALL have nothing behind them yet, so each is recorded FAILED saying it is not yet supported — see why an event type failed |
Eight $NOTIFY:* types are admitted and then refused | $NOTIFY:COMMAND, $NOTIFY:LOG, $NOTIFY:NETSEND, $NOTIFY:SNMP, $NOTIFY:SPOAL, $NOTIFY:SPOCO, $NOTIFY:TASKS and $NOTIFY:TEXTMSG are not carried out on this platform. The line is recorded FAILED with … is not supported on this platform and will not be applied. Remove this event or replace it with a supported one. — see why an event type failed |
$NOTIFY:EMAIL from a machine now sends mail. It is the one $NOTIFY type the platform carries
out, and a line that names it is applied like any other: the addresses, subject and body come off the
line, and the message goes out through the same Email channel a notification group uses. A non-empty
attachments field fails the line — there is no filesystem here to read attachment paths from. See
Sending mail with $NOTIFY:EMAIL.
$MACHINE:STATUS from a machine now takes it out of service. The line names the machine and a
status, and Continuum sets the agent's operator mark
— the same mark as Mark Offline, Mark Draining and Clear Mark on the agent's menu:
| Status on the line | What the agent is set to |
|---|---|
U (Up) | Active — any mark is cleared |
D (Down) | Marked Offline |
L (Limited) | Marked Draining — running jobs finish, no new work is sent |
The status letter is matched without regard to case. Setting the status the agent already has changes nothing, and keeps the reason an operator recorded on the mark; a mark the event changes carries no reason. The service account needs the Agents Edit permission.
The machine is then found by name across the tenant, ignoring case and surrounding spaces. A name more than one agent has fails the event with … matches 2 machines; rename them so the name identifies one machine.
$MACHINE:MAXJOBS failing is deliberate rather than a defect. A green row for it would say a limit
had been applied when nothing enforces one — the same rule the event log applies to
every event type the platform cannot act on. The relay's own concurrent-job setting is what caps
how many jobs run.
$TOKEN:ADD, $TOKEN:SET and $TOKEN:DELETE are accepted and applied exactly as
$PROPERTY:ADD, $PROPERTY:SET and $PROPERTY:DELETE — the same fields, the same rules, the same
permission check and the same masking of the value. The event log records them under the
$PROPERTY type. Event files that use the older spelling therefore work unchanged.
$JOB:REVIEW is accepted too, as the Classic spelling of $JOB:UNDERREVIEW: the same four
fields and the same permission, recorded under $JOB:UNDERREVIEW.
$PROPERTY:ADD, $PROPERTY:SET and $PROPERTY:DELETE reach global, OI., instance-scoped
and machine-scoped properties. An MI. name writes one of an agent's
machine properties, so a script can report a per-machine
measurement under a machine-scoped name:
$PROPERTY:ADD,MI./usr,93,<login ID>,<token>
With the machine part left blank, as here, the property is written on the machine that sent the
line. A line may also name another agent, MI.DISK_PCT.AIX53: unlike $MACHINE:STATUS, a
$PROPERTY line is not limited to the originating machine. A name no agent has fails the event
with Machine not found: <name>. The service account needs Agents Edit under
All workspaces. The other rules are in
Writing a machine property.
A line can also write a property onto a run — SI. for a workflow instance, JI. for a job
instance.
From a machine, name the workflow and its schedule date in full: SI.DISK_PCT.20260930.NIGHTLY,
or JI.DISK_PCT.20260930.NIGHTLY.EXTRACT. The shorthand that leaves those parts blank defaults them
from the job or workflow that raised the event, and a line written into MSGIN was not raised by
either, so a blank part is refused with a message naming it — for a blank schedule name, Cannot
default schedule name: event has no triggering instance. See
Writing a property onto a running instance.
Tracked and queued jobs
A z/OS agent raises three events of its own to bring a job it sees on the mainframe under the control of its schedule. Only an agent raises them — see Events only an agent raises — and they land on a z/OS Tracked Job or z/OS Queued Job defined on the workflow:
| Event | Line | What it does |
|---|---|---|
| Track Job | $JOB:TRACK,<Schedule Date>,<Schedule Name>,<Job Name>,<Frequency Name>,<Tracking Data> | A job submitted outside OpCon has started on the mainframe. The job is added to the workflow instance already started, as Wait to Start (Forced), and sent to the agent without waiting for its dependencies |
| Queue Job | $JOB:QUEUED,<Schedule Date>,<Schedule Name>,<Job Name>,<Frequency Name>,<Tracking Data> | The agent is holding a job. The job is added to the workflow instance and released to the agent when its dependencies are met |
| Update Queued Job | $JOB:QUESTATE,<Schedule Date>,<Schedule Name>,<Job Name>,<Job Status>,<Tracking Data> | Job Status I updates the queued job's termination description; any other value starts it now |
Tracking Data is the agent's reference for the job, id|machine|description, optionally
followed by |name=value;name=value properties to set on the job instance. The job is sent to the
agent with id|machine, so the agent can match it to its own job, and the description becomes the
job's termination description. The trailing credential pair follows, as on every line.
- A blank Schedule Date means today; a blank Schedule Name means the workflow named
AdHoc. The workflow instance must already be built for that date — none is built on demand — and there must be only one: these events have no Named Instance field. - Job Name is matched ignoring case among the jobs of the workflow as deployed, and the job must
be a z/OS Tracked Job or z/OS Queued Job. Frequency Name works as Added Job's Frequency does on
$JOB:ADD: it can be left blank only when the job has one frequency. - The line must name the machine that raised it, as the
machinein its Tracking Data, ignoring case and trailing spaces. The job is assigned to that agent. - An Update Queued Job line finds the job by its name, or a numbered copy of it, by the agent's reference and by the agent it is assigned to. Once the job has been sent to the agent, a line that would start it is refused and changes nothing.
The service account a verified line belongs to needs Job Instances Create for Track Job and Queue Job, and Job Instances Execute for Update Queued Job, in the workflow's workspace and the event's environment. A line that uses the compatibility pair is checked against no roles, but is held to the machine's own Tracked and Queued jobs all the same. What happens when the job is already in the workflow instance is in What happens when the agent reports one.
What the agent is told
A refused Track Job or Queue Job line is answered. The agent is sent one short message naming why, so it can act on the job it is tracking or holding rather than wait:
| Why the line was refused | The message |
|---|---|
| The Schedule Date cannot be read | Missing/Invalid d |
| The job is not on the workflow | Master Not Found |
| The Frequency Name is not one of the job's | JSKD Not Found |
| A Queue Job line for a job already running, or already added by an earlier report, that is not multi-instance | Duplicate Job |
| The job could not be added after the line was checked | Job Not Added |
| The relay could not build the job to send back to the agent | Error Building TI |
| Anything else — the workflow is not built for that date or has more than one instance, the job is not a Tracked or Queued Job, the line names another machine, or the credential or permission is refused | Invalid Event |
An accepted Queue Job line is answered too: the agent is sent the job as it will run, so it knows the job was accepted. When the relay cannot build it, the agent is sent Error Building TI instead, the job is still added, and it fails when it is released, with the same reason.
No message is sent for an Update Queued Job line, for a line whose Tracking Data does not
hold at least id|machine, or when the outcome is not known — a timeout, say, after which the job
may in fact have been added. A relay that predates these events sends no message.
Records and Rejections
How an agent-raised event is attributed
In the event log, an event raised this way shows:
- Source
AGENT, and anAGENTactor naming the machine that raised it. The machine stays the actor even now that the credential is verified, because that is the field operators filter on. - The service account the credential belongs to — the name the identity system returned, not the name the line claimed. The two agree apart from case, and the record keeps whichever the account actually has.
- The event line as received, with the credential pair removed. Property tokens are shown as written, not as they resolved.
The identity field tells you which of two things happened:
| What the record shows | What it means |
|---|---|
| A verified service account name | The credential was exchanged and checked out, and the account was permitted the event |
| The compatibility pair | The line used SYSTEM/MESSAGE and carries no identity at all |
That is more than the legacy behaviour offered: the file name, line number, emitting process and machine-side timestamp are not on the wire and so are not recorded. The machine name is, and it is the attribution to trace from.
Where a rejected event goes
This matters more than it usually would, because the machine deletes the event file before Continuum
has acknowledged anything. There is no error file written back to the machine — there is no
channel for one — so the platform's own record is the only trace. The one exception is a refused
$JOB:TRACK or $JOB:QUEUED line, for which a z/OS agent is sent a short reply — see
What the agent is told.
Rejections split into two groups, and only one of them is visible to you:
| Rejected | Where you see it |
|---|---|
At the platform edge — unknown event type, wrong field count, surplus values, an unset Default event environment, a $MACHINE line naming another machine or using a wildcard, a tracked or queued job line naming another machine, a credential that fails verification, a service account without the permission the event needs, a tenant with no identity configuration, a line over 4,096 bytes (which takes its whole batch with it — see Delivery), a property token that cannot be resolved, a line whose tokens resolve to more than 256 KB, or an event type the compatibility pair does not cover | Not in the event log. The line never became an event. It is recorded in the platform's operational logs with the machine name, the event type and the reason |
| After the event was accepted — no handler for the type, a refused scope, a downstream failure | In the event log, as a FAILED event with the AGENT source, the machine name, and the error on its detail view |
If a machine's event file is not producing anything and nothing appears in the event log for it, that is consistent with the line being refused at the edge — most often an unset Default event environment or a field count that does not match. Confirm the setting first, then contact support with the machine name and the event type.
Secrets in an agent-raised event
$JOB:ADD, $JOB:ADDHLD, $SCHEDULE:BUILD and $SCHEDULE:BUILDHLD carry a properties field as
Name=Value;Name2=Value2, and event files are written by hand — so a password can end up in one.
When one of these is raised by an agent and its properties field holds a value, that field and the values after it are replaced with a placeholder before the event is stored. The event is still applied with what the script sent; only the stored record is redacted. Two consequences:
- The stored record shows a placeholder rather than the properties you sent, and the verbatim line is not kept for that event. The parsed fields are all still there.
- Retry is refused for such an event, and the message says so: the original value cannot be recovered, so it has to be raised again from the machine that produced it.
An event that authors no properties value is unaffected and keeps its full record.
A $JOB:ADD from an agent never names an instance after a property value. A $JOB:ADD or
$JOB:ADDHLD for a multi-instance
job that carries properties adds one
instance. From any other source, a first property value that names one of the job's instances adds
that instance, and any other value adds an ad-hoc instance named from it. Raised by an agent, the
value is never read as a name: the add is always an ad-hoc instance, named AdHoc — numbered
AdHoc$0001, AdHoc$0002… if that name is already in use. A job's name is shown in every listing
and log entry of the job and is returned in the event's own state changes and messages, none of
which the redaction above covers, so a value promoted into it would be readable in all of them. The
property values themselves are still set on the instance, exactly as the line sent them.
Delivery and Platforms
Delivery: at most once, and lossy
The channel is not a queue, and this is the legacy behaviour rather than a Continuum choice — the installed agents delete the file before the platform acknowledges anything.
- An event can be lost. A send failure loses the line, and on UNIX/Linux it loses the rest of the file with it, so partial application of a multi-line file is a reachable outcome.
- The relay forwards lines in batches of up to 100, which can come from any of the machines behind it. A batch the relay cannot deliver is dropped whole, and so is a batch the platform refuses whole — which is what happens when any one line in it is over 4,096 bytes. One oversized line can therefore lose up to 99 other events, from other machines as well as its own. Keep every line under 4,096 bytes.
- A line sent twice is applied twice. The relay gives each line its own identity when the line arrives from the agent, so the relay's own retries of a batch are recognised and applied once — but if the agent sends the same line again, it arrives as a new event. Two files with identical contents are likewise two separate events, which is correct — a script reporting the same measurement on a schedule is meant to record each one.
- Ordering must not be relied on, either across files or between lines of one file. If one event has to be applied before another, put them in separate files and wait for the first to appear.
For anything where the outcome matters, treat an event file as a request that usually arrives, and
confirm the result rather than assuming it. The event log, filtered to source AGENT, is where to
confirm.
Platform differences on the machine side
These come from the installed agents and cannot be corrected by the platform, so they are worth knowing when an event file works on one machine and not another.
| Situation | UNIX/Linux | Windows |
|---|---|---|
A line with no leading $ | The agent adds one, so the line still works | Sent as-is, and refused as an unknown event type |
| Very small files | A file of 16 bytes or fewer is ignored and never deleted, so it accumulates in the directory | Handled normally |
| A file still being written | Waits for the file to stop changing | Can read a partly-written file, producing a truncated line that is then refused |
| Non-ASCII text | Passed through byte for byte | Depends on the machine's own code page, and a UTF-8 byte-order mark corrupts the first line |
| Pickup delay | Up to the agent's polling interval — 5 seconds by default | Under a second |
$Both make a file behave the same way on either platform. On Windows, save without a byte-order mark.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Nothing happens, and no event appears in the log | No Default event environment on the agent, or the line's field count is wrong | Look for the no default event environment warning on the Agents tab, or open the agent with Edit Agent; an agent registered before the field became required can still be unset. Then check the line ends with the login ID and token values and has no trailing comma |
| Events from a machine stopped working after an upgrade, and nothing appears in the log | The credential is now verified and the line's token is not a service-account secret — or the login ID doesn't match the account the secret belongs to | Create an event identity named for the login ID already in the file and replace the token with its secret. See the credential pair |
$JOB:* or $SCHEDULE:* lines from a machine are refused while its $NOTIFY:* lines are applied | The emitter is using the SYSTEM/MESSAGE compatibility pair, which covers only eleven event types — of the $JOB events, only the three tracked and queued job events | Give that emitter a real credential: an event identity's name and secret |
| A line with a correct credential is refused, and nothing appears in the log | The credential verified, but the service account's roles don't grant the permission that event needs in the workspace it names and the machine's Default event environment | On the identity's Roles tab, give it a role with that permission, scoped to that workspace and environment |
| An event is refused shortly after a role change in the identity system | The service account's role was withdrawn, so the credential no longer resolves or no longer carries the permission | Restore the role, or grant the account one that exists and is active |
| Several machines' events went missing at the same moment, and none appears in the log | One line in the relay's batch was over 4,096 bytes, so the whole batch was refused | Find and shorten the long line, then raise the lost events again |
| Every line from the tenant is refused, whatever the credential | The platform has no identity configuration for the tenant, so no line can be verified | Contact support |
The event appears as FAILED with $MACHINE:MAXJOBS is not supported yet | A $MACHINE:MAXJOBS line | It is not applied. The relay's concurrent-job setting caps how many jobs run |
A $MACHINE:STATUS line fails because the name matches several machines | More than one agent has that name | Rename the agents so the name identifies one |
The event appears as FAILED saying the type is not supported on this platform | One of the eight refused $NOTIFY types | Remove or replace the line. For mail, use $NOTIFY:EMAIL, which does work |
A $NOTIFY:EMAIL line fails naming attachments | Either the field really holds a path, or a comma in the message text shifted the text into it | Clear the field. The line format has no escape for a comma, so keep commas out of the message |
A $PROPERTY line with an MI. name appears as FAILED with Machine not found | The machine part names an agent that does not exist | Correct the name, or leave the machine part blank to write onto the sending machine |
A $PROPERTY:SET or $PROPERTY:DELETE line with an MI. name fails with Property not found | The agent has no machine property of that name | Use $PROPERTY:ADD, which creates it |
A $PROPERTY line with an MI. name is refused, and nothing appears in the log | The service account does not hold Agents Edit under All workspaces | Give the identity a role with that permission, granted in all workspaces |
A line carrying a [[…]] token is refused, and nothing appears in the log | The line carries a property token that does not resolve, or one scoped to a job, schedule or machine | Check the global property's name. A line raised this way can reach globals and the clock only — see Property tokens in an event line |
| The event applied to the wrong environment | The machine's Default event environment is not the one you expected | It is per machine, not per event. Change the setting, or raise the event from a machine registered to the right environment |
A $MACHINE:STATUS line for another machine is refused | Only the originating machine may be addressed | Raise it from that machine |
| Files pile up in the directory on a UNIX/Linux machine | Each is 16 bytes or fewer, so the agent ignores them | Pad the line, or combine the content into a larger file |
| The first line of a file is refused on Windows | A byte-order mark, or a line with no leading $ | Save as ASCII without a byte-order mark, and start every line with $ |
Contact support when
- A well-formed line with the environment set produces neither an applied event nor a
FAILEDrow in the event log. - An event applies but its recorded changes do not match what happened.
Include the machine name, the event type, the approximate time, and — if there is one — the event id and correlation id from the event log.