Skip to main content

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.
What this solves

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:

  1. Go to Agents › Connections and select New 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 Create.
  5. 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​

  1. 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.
  2. Fill in the account:
    • Windows — supply the DOMAIN\user login 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\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.
    • 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.
  3. Save. The Builder then picks it from the Connection field on the job.
A UNIX job must name a batch user

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​

SymptomCauseFix
A save is refused with "cannot be cleared"The edit sent an empty value for a secret fieldLeave 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 bothSupply 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 accountIt was saved as a service account before that option was removed, and still runs as oneLeave 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 userThose three platforms authenticate without a password. Windows and SQL both have one — and on SQL it is optionalRemove it.
A password is rejected for its charactersIt is 12 characters or fewer and contains a non-ASCII characterUse 13 characters or more, or keep it ASCII.
Test connection failsA required field is missing or empty, or a value is the wrong typeFix the reported field. This check never proves the system is reachable.
A connection type isn't availableIts plugin isn't enabledEnable the plugin. See Manage plugins.
A legacy job fails at dispatch naming a missing login, password, user, or groupThe attached batch user is incompleteComplete the connection.

Related topics