Manage connections

A connection stores configuration and credentials once, so jobs can use them without anyone embedding a secret in a workflow. You create and maintain connections; Builders attach them to jobs.

Two things live here:

• 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, IBM i, and SQL platforms.

What this solves

Every job that reaches an external system needs its endpoint and credentials, and every legacy job needs an identity to run under. Embed those in each workflow and secrets sprawl, rotation is painful, and a changed password breaks jobs everywhere at once.

How connections work

• Each connection is created from a connection type, which defines the fields it needs. Connection types come from installed plugins: today the four database types (SQL Server, MySQL, Oracle, ODBC), the four batch user types (Windows, UNIX, IBM i, SQL), the OpCon MFT Compression Password and the two Episys credential types used by the UNIX Episys job types. More arrive as plugins are added. You cannot create a connection type yourself.
• The configuration is stored encrypted. When you reopen a connection, its non-secret values are shown and only the secret fields are blank.
• Names are unique, must not be blank, and are capped at 255 characters.
• Every connection has a Test Connection action. It checks the configuration against the type's schema — it does not contact the target system.

Create a connection

To create a connection, complete the following steps:

1. Go to Connections and add a connection.
2. Enter a name and choose the connection type (the type can't be changed after creation).
3. Fill in the configuration fields the type requires.
4. Select Test Connection to confirm the configuration is complete.
5. Save.

For the specific fields of each database type (and the SQL Server certificate/auth options), see Set up database connections. For the batch-user fields and their character and password rules, see Connections.

Define a batch user for a legacy job

1. Add a connection of the type that matches the platform — Windows Batch User, UNIX Batch User, IBM i Batch User, or SQL Batch User.
2. Fill in the account:
   • Windows — turn Use Service Account off and supply the DOMAIN\user login name and its password. Leave the switch on if the job should run as the agent's own service account.
   • UNIX — supply the User and the Group, as two separate values.
   • IBM i — supply the User Profile, or leave the default * to use the job description's own user.
   • SQL — supply the Login Name: a SQL Server login, or DOMAIN\user if the jobs using it authenticate to SQL Server as a Windows account. The password is optional here, unlike on Windows. The same connection works for either authentication mode — the job decides which.
3. Save. The Builder then picks it from the Batch User field on the job.

A UNIX job must name a batch user

On Windows and SQL a blank Batch User means "run as the agent's service account", and on IBM i it means "use the job description's default user". On UNIX there is no such fallback — a UNIX job with no batch user attached fails at dispatch.

Editing safely

When you edit a connection, secret fields appear blank and everything else reads back as stored. That's intentional:

• Leave a secret blank to keep its current value.
• Enter a new value to replace it.
• Deliberately blanking a secret is refused, so an ordinary edit cannot destroy a stored password.

A rename or a description change never needs the password re-entered.

Troubleshooting

Symptom	Cause	Fix
A save is refused with "cannot be cleared"	The edit sent an empty value for a secret field	Leave the field blank instead of clearing it, or supply a real new value.
A Windows batch user won't save without a password	Use Service Account is off, so the account is a named one and needs one	Supply the password, or turn the switch back on.
"'password' is not supported" on a UNIX or IBM i batch user	Those two platforms authenticate without a password. Windows and SQL both have one — and on SQL it is optional	Remove it.
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.
Test connection fails	A required field is missing or empty, or a value is the wrong type	Fix the reported field. This check never proves the system is reachable.
A connection type isn't available	Its plugin isn't enabled	Enable the plugin. See Manage plugins.
A job says its connection type isn't found	No connection of that type is attached to the job	Have the Builder attach the right connection.
A legacy job fails at dispatch naming a missing login, password, user, or group	The attached batch user is incomplete	Complete the connection.

Related topics

• Connections — full configuration reference and troubleshooting
• Set up database connections (Administrator)
• Legacy LSAM connectors
• Manage plugins (Administrator)