Prepare agents for connectors
- Synopsis
- Full Details
In briefMost connectors run on an agent, and some need software, settings or access in place on that machine before their jobs can run. A Universal Agent needs its allowed file paths and the script interpreters your Builders use; legacy job types need a running relay, reachable LSAM machines, the right batch user, and — for the newer job types and fields — a current relay.
- Wait for File watches only the agent's allowed directories.
OPCON_ALLOWED_FILE_PATHSreplaces the default list rather than adding to it, and the agent must be restarted. - Run Script uses the interpreter on the agent; PowerShell on Linux or macOS needs
pwsh. - Database work runs through the SQL LSAM job types, so the client software belongs on the SQL LSAM machine, not on a Universal Agent.
- The SAP lookups need the agent's Query Listener Port and SAP system details; z/OS JCL access needs its JORS Port. Running a lookup, or viewing JCL, needs Agents Execute under All workspaces; saving JCL also needs z/OS JCL Edit and a z/OS user ID.
- A relay that has not reported it can send a job's newer settings refuses the job, which goes to Initialization Error with RELAY_LSAM_FEATURE_UNSUPPORTED. Upgrade the relay first.
- A UNIX job, every MCP job, and an MS SQL Job, Oracle or MySQL job must name a batch user.
- A job aimed at an agent of another type is refused with LSAM_AGENT_TYPE_MISMATCH.
Most connectors run on an agent, and some need software or permissions in place on that agent first. This guide covers what to set up so connectors run reliably. A job can only be assigned to an agent, pool or group that matches the job's operating system and agent type. If nothing matches, the job can't be assigned.
A connector fails at run time because the agent is missing a driver, an interpreter, or access to a path. The failure looks like a job problem when it's really a setup gap on the machine.
File access
The Wait for File job can only watch files in directories the agent is allowed to use. By default the allowed directories are:
/tmp/var/tmp- the operating system temp directory
- the agent's working directory
To allow other locations, set the OPCON_ALLOWED_FILE_PATHS environment variable on the agent
to a comma-separated list of paths, then restart the agent. Setting this variable replaces
the default list rather than adding to it, so include any default directories you still need. A
path outside the allowed list fails immediately with an "outside allowed directories" error.
Script interpreters
The Run Script job uses the interpreter installed on the agent. OpCon Continuum does not provide it. Make sure the interpreter for the script types your Builders use is present:
| Script type | Requirement on the agent |
|---|---|
| Shell | Always available (cmd.exe on Windows, /bin/sh on Linux/macOS) |
| PowerShell | powershell.exe on Windows; PowerShell 7+ (pwsh) must be installed on Linux/macOS |
| Bash | /bin/bash present |
| Python | python (Windows) / python3 (Linux/macOS) installed and on PATH |
Database drivers and tooling
There is nothing to prepare on a Universal Agent for database work: it runs through the SQL LSAM job types on an existing SQL LSAM machine, which need their client software on that machine — see below.
Legacy LSAM agents
The UNIX/Linux LSAM and Windows LSAM connectors don't use the Universal Agent. They run through the relay, which forwards jobs to your existing LSAM machines. For these to work:
- The relay must be running and the target LSAM machines reachable. When a relay stops reporting, its legacy agents read Offline or Unknown on the Agents tab; that points here, not at the Universal Agent.
- A job's machine name must match the LSAM agent name registered with the relay, and that agent must be of the job type's own platform: a job aimed at an agent of another type is refused at dispatch with LSAM_AGENT_TYPE_MISMATCH. See A legacy job aimed at an agent of another type.
- A legacy job runs as the batch user attached to it — a connection you define once; see
Manage connections. On Windows and IBM i, and on the SQL
MS SQL Script, MS SQL DTExec and Other DB types, a job with no batch user falls back
to the machine's own default; on UNIX a batch user is required, and so it is on the SQL
MS SQL Job, Oracle and MySQL types. An Oracle or MySQL job's
batch user must also have a password. An SAP R/3 Job or SAP BW Process Chain takes no batch user: the
SAP agent signs on to SAP with the logon configured on it, so set that up on the agent machine.
A z/OS Batch Job takes no batch user either: its User ID field names the z/OS user the job
is submitted as, and left blank the job is submitted under the agent's own authority. A z/OS
Started Task, z/OS REXX Exec, z/OS Console Command, z/OS Tracked Job or z/OS
Queued Job takes no batch user and names no user. Every MCP
job, of all six types, must name an MCP Batch User, which holds the MCP usercode it runs
under. An OS 2200 Job takes no batch user: its User ID field names
the user, and
-SECURITY-uses the LSAM's security user. - SAP R/3, SAP BW, z/OS, MCP and OS 2200 jobs need a current relay, one that reports it can
run SAP R/3 and CRM, SAP BW, z/OS, MCP or OS 2200 jobs; an older relay refuses them at dispatch. A z/OS job's
pre-runs — Dataset, Message, Job/Task, Tape and REXX Pre-run — need a current
relay too, as do its Step Control rows and Restart options, an MCP job's Prerun, an
OS 2200 Job's LSAM Resolved Dependencies, an IBM i job's message monitors, spool files and
dynamic variables, and a Windows Command job's Process Priority other than Normal: a relay that has not reported it can send them — any relay older than this
release — is refused the job, which goes to Initialization Error with
RELAY_LSAM_FEATURE_UNSUPPORTED rather than running without them. A z/OS Tracked
Job or z/OS Queued Job needs a relay that carries the agent's reference for the job. A z/OS agent's name is at most 8 characters, saved in upper case. An MCP agent's name must end with a period, such as
MCPPROD.. Jobs on an SAP BW or OS 2200 agent can never be killed. A z/OS agent's jobs can list their output, and their JCL can be viewed or saved, only once its JORS Port is set. An SAP R/3 and CRM agent's Allow Kill is also off by default — turn it on if operators should be able to kill its jobs. An OS 2200 agent starts its jobs in XML unless its Job Start Format is set to Non-XML, and XML needs a relay that reports it can send it. See OS 2200 Job Start Format, SAP R/3 Job, SAP BW Process Chain, z/OS Batch Job, MCP Run and MCP Start, OS 2200 Job and Allow Kill. - For the SAP lookups, set the SAP agent's query port and SAP system details. The job editor's Search… on the SAP fields and Check SAP Job Numbers ask the agent about its SAP system, through the relay, on the agent's Query Listener Port; the agent signs on to SAP with the agent's SAP system details. Set both to match the agent's own configuration, and open that port from the relay to the agent machine. Whoever runs them needs Agents Execute granted under All workspaces. See Looking up the job and the server in SAP, SAP system details and SAP lookup permission.
- For z/OS JCL access, set the agent's JORS Port and assign z/OS user IDs. The JCL dialog reads and saves members through the relay on the agent's JORS Port, so open that port from the relay to the agent machine. Viewing needs Agents Execute under All workspaces; saving needs z/OS JCL Edit and a z/OS user ID for each person, assigned on the z/OS User IDs tab of the Permissions page. See Viewing and editing JCL and z/OS User IDs. JCL access is not available for an agent with Use TLS for Scheduling on.
- Oracle, MySQL and Other DB need their client software on the SQL LSAM machine. An Oracle
job runs SQL*Plus there, a MySQL job the mysql command-line client, which must be on the
machine's
PATH, and an Other DB job the ODBC driver or OLE DB provider its connection names — or the ODBC data source (DSN), which must be a system data source on that machine. Install them before these jobs run; see Oracle, MySQL and Other DB. - IBM i lists need a current relay. An IBM i job with message monitors, spool files or dynamic variables is refused at dispatch by a relay that has not reported it can send them, going to Initialization Error rather than running without its lists, and an older relay fails the IBM i Operator Replay, Restricted Mode, FTP and File Arrival job types. Upgrade the relay before these are used — see IBM i lists.
- Quoted Windows File Arrival names need a current relay. A Windows - File Arrival job whose file name is wrapped in double quotes, as migrated jobs often are, runs on a current relay. An older relay refuses any double quote in the file name, so the job fails at dispatch — see Quotes in the file name.
- A DTExec configuration file needs a current relay. An MS SQL DTExec job whose package is on the file system can name a Configuration File. A relay that has not reported support for it is not sent the job, which goes to Initialization Error rather than running the package without its configuration — see The configuration file.
- The Windows LSAM command job does not take an embedded script; a script from the script library runs as its own job type, Windows - Embedded Script. Per-job environment variables are supported on the command job.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| File job fails with "outside allowed directories" | The path isn't in the agent's allowed list | Add the location to OPCON_ALLOWED_FILE_PATHS (keep the defaults you need) and restart the agent. |
| Run Script job can't start the interpreter | Interpreter not installed on the agent (often pwsh or python3) | Install the interpreter on the agent and confirm it's on PATH. |
| A legacy job does not reach its LSAM machine, and the machine's agent reads Offline or Unknown | Relay down or LSAM machine unreachable | Check the relay and LSAM connectivity. |
| An SAP lookup or check reads The agent's query port could not be reached. | The agent's Query Listener Port is not the port it listens on, or the port is blocked from the relay | Correct the port on the agent, or open it from the relay. See SAP R/3 troubleshooting. |
Related topics