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 account a job runs as — the batch user types, for legacy Windows, UNIX, IBM i, SQL and MCP 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.
Some job types need a credential for a step, 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 enabled plugins: the five batch user types (Windows, UNIX, IBM i, SQL, MCP), the OpCon MFT Compression Password and the two Episys credential types used by the UNIX Episys job types. A database job signs on with a SQL Batch User. 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:
- Go to Agents › Connections and select New Connection.
- Enter a Name and choose the Connection Type (the type can't be changed after creation).
- Fill in the configuration fields the type requires.
- Select Create.
- Open the saved connection and select Test Connection to confirm the configuration is complete. The action appears only on a connection that has been saved.
For the batch-user fields and their character and password rules, see Connections.
Define a batch user for a legacy job
- Add a connection of the type that matches the platform — Windows Batch User, UNIX Batch User, IBM i Batch User, SQL Batch User, or MCP Batch User.
- Fill in the account:
- Windows — supply the
DOMAIN\userlogin name and its password; both are required. To run a job as the agent's own service account, create no connection: leave the job's Connection field empty. - 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\userif 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. - MCP — supply the Usercode: up to 17 upper-case letters and digits, or
*for the agent's default. There is no password; an access code, when the usercode needs one, goes on the job.
- Windows — supply the
- Save. The Builder then picks it from the Connection field on the job.
On Windows, and on the MS SQL Script, MS SQL DTExec and Other DB job types, a blank Connection 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. The other three SQL job types need one too: MS SQL Job, Oracle and MySQL. An Oracle or MySQL job's batch user must also have a password, because it is the database login. Every MCP job, of all six types, must name an MCP batch user as well.
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: "Enter a login name…" or "Enter a password…" | A Windows Batch User is always a named account, so it needs both | Supply both. For the agent's service account, leave the job's Connection field empty instead. |
| 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. |
| "'password' is not supported" on a UNIX, IBM i or MCP batch user | Those three 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 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
- Legacy LSAM connectors
- Manage plugins (Administrator)