Connections
- Synopsis
- Full Details
In briefA connection stores the configuration and credentials a job needs, encrypted, so no secret is embedded in the workflow. Batch users hold the account a legacy job runs as — for a SQL job, its database login; the other types hold a credential one job type needs. Each connection type comes from a plugin and declares which of its fields are secret.
WhereAgents › Connections, with New Connection on the list. A job attaches a batch user from its Connection field.
When
- A SQL LSAM database job needs a login.
- A legacy Windows, UNIX, IBM i or SQL job must run as a specific account, or an MCP job under a usercode.
- An OpCon MFT transfer needs a compression password, or an Episys job needs its credential.
- The same job needs a different credential in each environment.
How
- Open Agents › Connections and select New Connection.
- Pick the Connection Type, give it a Name, fill in its fields, and select Create.
- Select Test Connection on the saved connection to check its configuration.
- Attach it to the job, for a legacy job from the Connection field.
The full steps are in Manage connections.
- Secret fields read back blank. Leave one blank when editing to keep the stored value.
- Test Connection checks the configuration only; it never contacts the target system.
- A connection's type cannot be changed after it is created.
- Sending an empty value for a secret field is refused; it never clears the stored secret.
- A UNIX job must name a batch user, and so must an MS SQL Job, Oracle, MySQL or MCP job. On Windows and the other SQL types a blank Connection runs as the agent's own service account.
- To change credentials per environment, target the job's connection reference in a transformation rule, never the Connection parameter.
- The Episys credentials are visible in the job's output.
Task walkthrough: Manage connections. This page is the full configuration and troubleshooting reference.
A connection stores the configuration and credentials something needs, so a job can use it without embedding a secret in the workflow. Connections cover two things today:
- The account a job runs as — the batch user types, for legacy Windows, UNIX, IBM i and SQL platforms. For a SQL job, that is the database login it signs on with.
- A credential a job type needs for one step — the OpCon MFT compression password and the two Episys credentials.
Connections are defined by plugins and are schema-driven: each connection type declares the fields it needs, and which of them are secret.
- How It Fits
- Batch Users
- MFT and Episys Credentials
- Editing and Testing
- Attaching a Connection to a Job
- Troubleshooting
How It Fits
How connections work
| Concept | Notes |
|---|---|
| Connection type | Comes from an installed plugin's manifest and is identified by its name (for example batch-user-windows). It carries a display name, a configuration schema, and — derived from that schema — the list of secret fields. Connection types are catalog data: you cannot create, edit, or delete one. |
| Connection instance | A named connection you create from a type. Its whole configuration is stored encrypted. |
| Secret fields | Every field the type marks as a password. These are the fields that are masked on read and protected on write. |
| Test Connection | Validates the stored configuration against its schema and reports the result. It is a configuration check, not a connectivity probe — see Test connection. |
Connection names are unique within a tenant, must not be blank, and are capped at 255 characters. A name already in use is refused rather than silently reassigned.
The connection type cannot be changed after creation. Create a new connection instead.
Connection types available today
Eight types ship, from six plugins.
| Type | Plugin | For |
|---|---|---|
Windows Batch User (batch-user-windows) | Windows LSAM | The Windows account a legacy Windows job runs as |
UNIX Batch User (batch-user-unix) | UNIX/Linux LSAM | The UNIX user and group a legacy UNIX job runs as |
IBM i Batch User (batch-user-ibmi) | IBM i LSAM | The IBM i user profile a legacy IBM i job runs as |
SQL Batch User (batch-user-sql) | SQL LSAM | The database login — a SQL Server login, an Oracle or MySQL user name — or the Windows account a legacy SQL job runs as |
MCP Batch User (batch-user-mcp) | MCP LSAM | The MCP usercode a legacy MCP job, of any of the six MCP job types, runs under |
OpCon MFT Compression Password (opconmft-compression) | OpCon MFT | The password an OpCon MFT transfer uses to protect an archive it creates, or to open a protected one it downloads |
Episys External Event Credential (episys-event-credential) | UNIX/Linux LSAM | The OpCon user and External Event Password the Episys Find job types send a property update with |
Episys FTP Credential (episys-ftp-credential) | UNIX/Linux LSAM | The FTP user and password Episys: FTP all Reports in List logs in with |
The framework is extensible — new connection types arrive with new plugins. The built-in command, script, file-wait, and internal job types need no connection.
Batch Users
A batch user is the account a legacy job runs as. Define it once as a connection, then pick it from the Connection field on the job. The password never appears in the workflow definition and is never returned to the browser.
Windows Batch User
| Field | Required | Rules |
|---|---|---|
| Login Name | Yes | DOMAIN\user, up to 61 characters. ASCII only. Must not contain a | character, and must not start with Use Service Account. |
| Password | Yes | Up to 256 characters. See the ASCII rule below. Leave blank when editing to keep the current password. |
A Windows Batch User is always a named account: it needs a login name and a password. A named account stored without a password fails every dispatch rather than quietly falling back to the service account, so the save is refused instead. To run a job as the agent's own service account, leave the job's Connection field empty — no connection is needed for that.
A Windows connection saved as a service account in an earlier release keeps running as one. Its page says Runs as the agent's service account. To turn it into a named account, enter a login name and a password and save; changing the login name without a new password is refused with "Enter a password to run this connection as a named account."
UNIX Batch User
| Field | Required | Rules |
|---|---|---|
| User | Yes | 1–31 characters, ASCII only. Must not contain /, and must not contain any of ` ~ ! @ # $ % ^ & * = + < > ( ) [ ] { } | ; ' : " , . ? |
| Group | Yes | Same rules as User. |
User and group are stored as two separate fields rather than as one composite group/user
string — which is why neither may contain /.
IBM i Batch User
| Field | Required | Rules |
|---|---|---|
| User Profile | Yes | 1–31 characters, ASCII only. Default *, which means "use the job description's default user". |
SQL Batch User
| Field | Required | Rules |
|---|---|---|
| Login Name | Yes | The database login — a SQL Server login, or the Oracle or MySQL user name — or DOMAIN\user when the job authenticates to SQL Server as a Windows account. Up to 61 characters, ASCII only. Must not contain any of ` ; : " < > * + = | ? , — a backslash is allowed, because that is how a domain account is written. The literal Use Service Account means the job does not impersonate. |
| Password | No | Up to 256 characters, as on a Windows batch user. See the ASCII rule below. Leave blank when editing to keep the current password. |
One SQL batch user serves both authentication modes: whether its login name is used as a Windows account or as a SQL Server login is decided by the job's Windows Authentication setting, not by the connection. So the same credential can be attached to jobs that authenticate either way — see MS SQL Script.
MCP Batch User
| Field | Required | Rules |
|---|---|---|
| Usercode | Yes | 1–17 upper-case letters and digits, or * for the agent's default. |
An MCP batch user has no password. A usercode that needs an access code gets it on the job, in its Access Code field, so the same batch user can serve jobs with and without one. An MCP Start job can name a second MCP batch user in its Job Summary User field, for the usercode its job summary is kept under.
The rules that apply to every batch user
- A password is not accepted at all on UNIX, IBM i or MCP. Those platforms have no password field on the wire, and a password that was accepted and then ignored would leave you believing the job authenticates with it. Supplying one is refused.
- On SQL the password is optional, and that is deliberate. A SQL batch user saves with or without one: a job using Windows Authentication takes its database identity from the impersonated account and needs no password, while a SQL Server login usually has one. Unlike Windows, a named SQL account with no password is a legitimate configuration and is not refused when you save it. An Oracle or MySQL job is the exception: it refuses, at dispatch, a batch user with no password.
- Cleartext fields are ASCII only, at any length. The legacy connector currently transmits every
character above
U+007Fas?, so a non-ASCII login name, user, group, or user profile would not reach the agent as typed. - A password of 12 characters or fewer is ASCII only; 13 or more may contain any character. At 12 or fewer the agent's cipher takes a legacy branch that cuts multi-byte characters mid-sequence, so the agent would decrypt a different password than the one you set. Use 13 characters or more to keep non-ASCII characters, or keep the password ASCII.
- A field the type does not declare is rejected, rather than being stored and handed back.
MFT and Episys Credentials
OpCon MFT Compression Password
This type is not a batch user — it is not an account a job runs as. It holds the single password an OpCon MFT Transfer job uses to protect the archive it creates, or to open a protected archive it downloads.
| Field | Required | Rules |
|---|---|---|
| Compression Password | Yes | 1–512 characters. Stored encrypted and never shown again after saving. |
It is optional on the job: leaving the job's Compression Password field empty means the transfer uses no password. Because it is a connection rather than a value typed into each job, one password can be shared across many transfers and changed in one place.
Episys credentials
Two types serve the UNIX Episys job types. Like the MFT compression password, neither is a batch user — an Episys job names one of these as well as the UNIX batch user it runs as.
| Type | Fields | Rules |
|---|---|---|
| Episys External Event Credential | OpCon User (1–255 chars), External Event Password (1–200 chars) | Neither may contain a double quote: the password is sent in double quotes. |
| Episys FTP Credential | FTP User (1–256 chars), FTP Password (1–256 chars) | Neither may contain spaces: both are passed unquoted. On an agent that runs jobs through the shell — the default — characters such as $ ` \ & and ; in the password are interpreted by the shell. |
These character rules are not checked when you save the connection. A job whose credential breaks one fails when it is sent to the agent, with a message naming the field.
On both, leave the password blank when editing to keep the one already stored.
The UNIX agent prints the full command line at the top of a job's output, and for the Episys job types that use these connections, the command line contains the password. Anyone who can read the job's output can read the credential. Give these accounts the narrowest rights that let the utility work, and see An Episys credential appears in the job's output.
Editing and Testing
Reading and editing a connection
Reads return the configuration with non-secret values in the clear and every secret field
null — so you can see which server or account a connection points at without re-entering
anything. Nothing ever returns the encrypted value, and nothing returns a placeholder string that
could be saved back as the literal password.
That shapes the edit rules:
| What you send | What happens |
|---|---|
| The field is absent from your edit | The stored value is kept. This is how "leave the password blank to keep it" works. |
| A new value | Re-encrypted and stored. |
An empty string or null on a secret field | Refused. Clearing a secret is never what an edit meant, and the read model returns null for every secret — so echoing a read back into a save would otherwise destroy it. |
Only the keys you actually send are changed; everything else in the configuration survives the edit. A rename on its own is always safe, and a connection that is missing a required value can be repaired by supplying it.
- A description-only or name-only edit never touches the configuration and never needs a password.
- If the plugin that defines a connection's type is no longer installed, the connection still lists — but its whole configuration reads back masked, and its configuration cannot be edited until the plugin is available again. The type column falls back to the raw type name.
- Deleting a connection is a soft delete. The name is released for reuse.
Test connection
Test Connection validates the stored configuration and returns success or failure, a list of errors, a list of warnings, and how long the check took. What it checks:
- every field the schema marks required is present and not empty;
- each value is of the declared type, and meets any declared minimum length;
- it warns when a password is shorter than 8 characters.
It does not open a network connection, authenticate, or contact the target system — so a connection that tests successfully can still fail at run time on credentials, certificates, drivers, or reachability. For a database job, the job's own failure output is the evidence to read. For a legacy job, see Legacy LSAM connectors.
Attaching a Connection to a Job
A job carries at most one connection reference. For a legacy job that reference is its batch user, and it is set from the Connection field on the job — a picker of the connections whose type matches the job's platform. The picker searches by connection name.
The OpCon MFT Compression Password, the Episys credentials and an MCP Start job's Job Summary User are not that reference: the job picks them in fields of their own, and they are sent to the agent alongside the batch user.
The picker is filtered on every legacy platform, so it offers only batch users the platform's agent can resolve.
What a blank Connection field means depends on the platform, and the difference matters:
| Platform | Connection left blank |
|---|---|
| Windows | The job runs as the agent's own service account. This is a legitimate, deliberate configuration. |
| IBM i | The job runs under the job description's default user (*). |
| SQL — MS SQL Script, MS SQL DTExec, Other DB | The job runs as the agent's own service account and does not impersonate, whichever way Windows Authentication is set. |
| SQL — MS SQL Job, Oracle, MySQL | Not allowed. These job types must name a SQL batch user; without one the dispatch fails. |
| UNIX | Not allowed. A UNIX job must name a batch user; without one the dispatch fails. |
| MCP | Not allowed. Every MCP job, of all six types, must name an MCP batch user; without one the dispatch fails with RC_MCP_NO_BATCH_USER. |
On every legacy Windows, UNIX, IBM i, SQL and MCP job type, an attached batch user must be of its own platform's type. A job with a connection of the wrong type is refused at dispatch rather than degrading to the service account.
Per-environment credentials
A deployment can point the same job at a different credential per environment with a deployment
transformation rule targeting the job's connection reference —
$.jobs[*].connectionRefs[0].id. That is the supported way to do it.
The Connection value you see in the job's parameter list and in the Code view is a display
mirror of that reference, and no transformation rule may change it. A rule aimed at
taskDefinition.parameters.batchUserId is refused when you save it, because a rule there would look
active and change nothing — the job would authenticate as the source environment's account. See
Versions and deployments.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| A save is refused with "cannot be cleared — omit the field entirely to keep the current value" | The edit sent an empty value for a secret field | Remove the field from the edit, or supply a real new value. |
| A save is refused with "is not a recognised field for connection type…" | The edit adds a key the type does not declare, or changes the value of one the connection still holds from before the type dropped it | Remove the extra key, or leave its stored value as it is. A key the connection already holds, sent back unchanged, does not block a save — so a connection whose type has since renamed or removed a field can still be edited and renamed. |
"'password' is not supported for connection type 'batch-user-unix'" (or -ibmi, -mcp) | A password was supplied for a platform that has none | Remove it — those platforms authenticate without one. |
| A Windows batch user will not save: "Enter a login name…" or "Enter a password…" | Every Windows Batch User is a named account and needs both | Supply both. To run the job as the agent's service account, leave the job's Connection field empty instead of creating a connection. |
| An older Windows connection says Runs as the agent's service account | It was saved as a service account before that option was removed, and still runs as one | Leave it, or enter a login name and a password and save to make it a named account. |
| A password is rejected for its characters | It is 12 characters or fewer and contains a non-ASCII character | Use 13 characters or more, or keep it ASCII. |
| A SQL batch user is refused with "contains a character Classic rejects" | The login name uses one of ` ; : " < > * + = | ? , | Remove it. A backslash is fine — DOMAIN\user is the expected form for Windows Authentication. |
| A legacy job fails at dispatch: no login name / no password | The attached Windows batch user is a named account missing one of them | Complete the connection (Administrator). |
| A UNIX job fails at dispatch: Missing required field: user (or group) | No batch user is attached, or its user or group is blank | Attach a complete UNIX batch user (Builder/Administrator). |
| A legacy job fails at dispatch: attached connection is not a … credential | The job's connection is of the wrong platform's type — often from a hand-edited config, an import, or a transformation rule | Re-pick the batch user on the job (Builder). |
| Test connection fails | A required field is missing or empty, or a value is of the wrong type | Fix the reported field. Note this is a configuration check only — it never proves reachability. |
| A connection type you expect isn't listed | Its plugin isn't installed or enabled | Check plugin installation (Administrator) — see Plugins. |
The Host column shows - on every row | That column reads a metadata value that connections do not currently set | Open the connection to see what it points at. |
| An edit is refused with "connection type … is not available" | The plugin defining the type is not installed | Restore the plugin, then edit (Administrator). |