Skip to main content

Events raised by a legacy agent

BETA Preview

This feature is still being finalized by Development.

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

  1. Set the agent's Default event environment.
  2. 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.
  3. Put the identity's secret in the emitter's configuration as the token.
  4. Write each line as $TYPE:ACTION,<values>,<login ID>,<token>, in plain ASCII with a leading $.
  5. 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.

Notes
  • 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 FAILED because the platform does not carry them out, among them $MACHINE:MAXJOBS and eight $NOTIFY types.
  • A line can reach global properties and the clock, not job-, schedule- or machine-scoped tokens.
  • A $PROPERTY line with an MI. name writes a machine property: the sending machine's when the machine part is blank, or the agent it names.
  • A $JOB:ADD with properties for a multi-instance job always adds an ad-hoc instance named AdHoc, because a value from a machine is never used as a name.
  • A z/OS agent's $JOB:TRACK, $JOB:QUEUED and $JOB:QUESTATE lines 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.
Watch out
  • 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/MESSAGE pair 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.