Process Task

The Process Task runs an external process.

Typical uses are to:

• Launch a report writer to generate or print reports — Crystal Reports, SSRS or Stonefield.
• Run a process or batch at the completion of an integration, as part of a wider process automation.
• Hand a file to a command-line tool that has no task of its own.

The task does not read or write the dataset, so it has no Field Mapping tab. It reads the data in one place only: IMan expands the Command against it.

Setup

Transform Id, Description and Priority are the same on every transform and are described under Transform > Setup.

Command

The program to run, and its arguments.

The whole string is one field. IMan takes the first item as the program and everything after it as the arguments.

A program path containing spaces must be double-quoted

A program path containing spaces must be double-quoted. If it is not quoted, IMan splits the command at the first space. It reads C:\Program Files\Tool\run.exe as the program C:\Program with Files\Tool\run.exe as its first argument, and the task fails with "Cannot launch process [C:\Program Files\Tool\run.exe]."

IMan catches an opening quote with no closing one before anything runs: "Error parsing command […] into an command and arguments. It is likely the command has an unterminated quote mark."

The field can reference the dataset (Expando Fields), and IMan launches one process for each value the command expands to. A command with no field reference runs once. A command that references a field of a transaction with fifty records runs fifty times.

Type % to open a picker of every available field, grouped by transaction and labelled with each field's type. The picker is the reliable way to enter a field reference.

A field reference here must be bracketed and qualified

A field reference here must be bracketed and qualified by its transaction — %[Transaction.Field].

These are two separate rules, and the field checks both as you type:

• IMan refuses an unqualified reference with "'%[OrderId]' is an unqualified field reference - merge fields are entered as %[Record.Field]." IMan does not evaluate the Command against any particular transaction, so it has no record to assume. A reader's Url For Steppable Reader is different: it belongs to one transaction, so it accepts a bare field name.
• Without brackets, only a space or the end of the string ends %Transaction.Field. Any other character after it, such as a quote or a slash, becomes part of the field name: "%Root.OrderId" looks for a field called OrderId". Use the brackets. An opening %[ with no closing ] fails the task outright with a parse error.

Example

"C:\Program Files\Reports\OrderAck.exe" /order %[Root.OrderId] /out D:\Ack

A quoted program path, producing one acknowledgement per order. Root is the transaction (the name a reader gives the records of a file with no hierarchy) and OrderId is the field within it.

Working Directory

The working directory the process runs in.

If left blank, the process uses the directory the program itself is in.

Unlike Command, this field is not expanded against the dataset. IMan reads it once when the task starts and passes any field reference through as written.

Maximum Simultaneous Processes

How many of the expanded commands may run at the same time.

When set to 1, each process runs to completion before the next starts. When set higher, that many run at once and the rest queue behind them. 0 behaves as 1. The maximum is 99.

Set this with care where a command expands over a large transaction. The default of 1 is safe but slow. A high value on a thousand-record dataset will start a thousand processes as fast as the machine allows.

User Id

The user to run the process as.

If left blank, the process runs in the security context IMan itself runs under: the Scheduler service at runtime, or the Data Preview service when you preview from the designer. That account's permissions apply, and it is often not the account you are signed in as while you build the integration.

You can give the user in User Principal Name form, [email protected]. If you do, leave Domain empty.

Domain

The domain of the user named above.

Leave it blank when no user is given, or when the user is in UPN form.

Password

The password of the user named above. IMan stores it encrypted and decrypts it only when it launches the process.

IMan masks the saved password. The box shows ********, followed by the last three characters when the password is eight or more characters long. Press the eye button beside the box to show the stored password, and press it again to hide it. Showing a stored password needs the Can reveal a stored secret in full permission. To change the password, click in the box and type the new one. Leave the box empty to keep the stored password.

Leave it blank when no user is given.

What the exit code does

The task reads each process's exit code. It treats the two kinds of non-zero result differently.

Exit code	Treated as
0	Success
Negative	An error, reported with the code in hexadecimal and any output the process wrote to standard error
Positive	A warning, written to the Audit Report and nothing more

A positive exit code does not fail the integration

A positive exit code does not fail the integration. Many command-line tools signal failure with exit code 1. IMan records that as a warning and carries on to the next transform.

If a non-zero result must stop the run, wrap the command in something that turns the result into a negative code, or check the outcome afterwards. You can check it with a Script task, or by testing for the file the process should have produced.

A negative code usually comes from the operating system, not the program, and IMan treats it that way. It reports the code in decimal and hexadecimal and says the process "failed to initialise or terminated abnormally before running any application code." For example, -1073741819 is 0xC0000005, an access violation.

Audit

Supported counters

• ERRORS — incremented for each command that could not be launched.

Action on Transform Error

Unlike most tasks, the Process task honours this setting.

• Abort — the integration stops on the first command that will not launch.
• Reject Record and Continue — IMan logs the failure to the Audit Report and the task carries on with the remaining commands. The two behave identically here.

The setting applies only to commands that could not be started, such as a missing program, a bad path or a rejected logon. A process that starts and then fails is judged on its exit code, described above. This setting does not affect it.

The setting and the rest of the tab are described on Transform > Audit.