Connections

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 endpoint and login for an external system — the database connection types.
• The account a job runs as — the batch user types, for legacy Windows, UNIX, and IBM i platforms.

Connections are defined by plugins and are schema-driven: each connection type declares the fields it needs, and which of them are secret.

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

Eleven types ship, from six plugins.

Type	Plugin	For
SQL Server (database-sqlserver)	SQL Database Executor	SQL Server (server, port, database, SQL or Windows auth, certificate trust)
MySQL (database-mysql)	SQL Database Executor	MySQL (host, port, database, username, password)
Oracle (database-oracle)	SQL Database Executor	Oracle (connection string, username, password)
ODBC (database-odbc)	SQL Database Executor	Any ODBC/OleDB database (connection string, username, password)
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 SQL Server login — or Windows account — a legacy SQL job runs as
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 field details for the database types are in Set up database connections. 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.

note

On an Oracle or ODBC connection the Connection String is treated as a secret, not just the password beside it. An ODBC/OleDB string conventionally carries the password inline, so it is masked on read the same way a password is, and the same "leave blank to keep it" rule applies.

Batch users

A batch user is the account a legacy job runs as. Define it once as a connection, then pick it from the Batch User 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
Use Service Account	Yes	On (the default) runs the job as the agent's own service account, and no login name or password is needed.
Login Name	Required unless Use Service Account is on	DOMAIN\user, up to 61 characters. ASCII only. Must not contain a | character, and must not start with Use Service Account.
Password	Required unless Use Service Account is on	Up to 256 characters. See the ASCII rule below. Leave blank when editing to keep the current password.

A named Windows account must have a password. A named account stored without one fails every dispatch rather than quietly falling back to the service account, so the save is refused instead.

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 SQL Server login, 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 512 characters. 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.

The rules that apply to every batch user

• A password is not accepted at all on UNIX or IBM i. 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.
• Cleartext fields are ASCII only, at any length. The legacy connector currently transmits every character above U+007F as ?, 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.

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)	The password is sent in double quotes, so it may not contain a double quote.
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.

On both, leave the password blank when editing to keep the one already stored.

These two credentials are visible in the job's output

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.

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.

Good to know

• 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 Batch User field on the job — a picker of the connections whose type matches the job's platform. The picker searches by connection name.

The picker is now filtered on every legacy platform. It previously offered an unfiltered list on IBM i, so credentials belonging to other platforms appeared as choices even though the IBM i agent could never resolve them.

What a blank Batch User field means depends on the platform, and the difference matters:

Platform	Batch User 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	The job runs as the agent's own service account and does not impersonate, whichever way Windows Authentication is set.
UNIX	Not allowed. A UNIX job must name a batch user; without one the dispatch fails.

Every legacy Windows, UNIX, IBM i, and SQL job type requires a batch-user connection 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 Batch User 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 configuration carries a key the type does not declare	Remove the extra key.
"'password' is not supported for connection type 'batch-user-unix'" (or -ibmi)	A password was supplied for a platform that has none	Remove it — those platforms authenticate without one.
A Windows batch user will not save without a password	Use Service Account is off, so the account is a named one	Supply the password, or turn Use Service Account back on.
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: no user / no 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).
A job reports its connection type "not found"	No connection of the required type is attached	Attach a matching connection to 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 is empty on every row	That column reads a metadata field nothing populates yet	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).

Related topics

• Manage connections (Administrator)
• Set up database connections (Administrator)
• Legacy LSAM connectors
• Job configuration
• Versions and deployments
• Plugins