Run External Program Tool

What is the Run External Program Tool?

The Run External Program tool runs self-terminating shell executable programs including .exe or .bat for example, or any file type that is associated with such a shell executable program. Programs can either be existing programs that exhibit the right attributes or programs specially created to provide integration with proprietary protocols, systems or applications.

As well as the flexibility to create a program that performs virtually any operation, the behaviour of the program can also be controlled dynamically at run-time. To enable this, the step can pass static or dynamic command-line parameters to the program when run. The program can be run once or multiple times, depending on configuration.

Recordsets from an Input step, such as Database Query (ODBC), or document source recordsets from a Format step, such as an Format as HTML or Format as Text can be used to provide the values of dynamic data.

Run External Program Tool Features

• Run any self-terminating shell executable (.exe, .bat, .com, and so on)
• Run files associated with self-terminating shell executables
• Pass static or dynamic command-line parameters
• Use source data from other actions
• Execution failure options
• Memory features to memorise task data created at run-time

White Paper - Run External Program

The Run External Program white paper describes how to use the tool.

Download White Paper

Run External Program Tool: Working with other Tools

The Run External Program tool can directly interact with the following tools:

Consuming from Other Tools

The Run External Program can consume the output from the following tools:

Icon	Tool Name	Tool Category
	Database Query (ODBC)	Input and Data Connectors
	Database Query (OLEDB)	Input and Data Connectors
	Import Flat File	Input
	Convert XML to Recordset	Format
	Create Workflow Job	Format
	Format as Flat File	Format
	Format as HTML	Format
	Format as HTML Pro	Format
	Format as Text	Format
	Run Crystal Report	Format
	Run Microsoft Reporting Services	Format
	Run Microsoft Word (Merge)	Format
	Filter Data	General

Objects Consumed

The following objects are exposed by the above tools and can be consumed by the Run External Program tool:

• Recordset — Tabular data outputted by Input steps
• Documents (Text) — Documents outputted by Format steps

Exposing to Other Tools

As an Output category tool, Run External Program does not expose any objects that can be directly consumed by another tool. However, it does expose the following objects which can be used in a task step sequence:

• RecordSource — If an Input Recordset has been selected (see General tab), this contains the columns
  included in the recordset
• DocumentSource — If a Document Source has been selected (see General tab), this contains the data in the document as recordset columns
• Memory Definitions — If configured, this is a list of Memory Definitions created for the step and the recordset columns to be memorised for each one
• Step Properties — Standard step properties are available allowing you to use statistical data of the tool

Step Configuration

To add a new Run External Program step to an existing task, you either:

• Click and drag the Run External Program icon from the Task Browser to the task Design area.
• From the task’s Design tab, right-click on empty space and select Add > Execute > Run External Program.

For a detailed description of how to create new tasks, refer to the product help.

About the General Tab

The General tab is used to enter the following details for the step:

• Name — Enter a meaningful name for the step
  TIP: If this task instance makes use of two or more Run External Program steps, ensure the Name used is
  unique for each individual step.
• Description — If required, enter a description of this step
• Use a Recordset — Enable this parameter if recordset data from a previous task step is required when running the external program
  • Input Recordset — Contains all available recordsets from steps previously created in the task
• Read documents from a source — Enable this parameter if document data from a Format task step is required when running the external program
  • Document Source — Contains all available documents from Format steps previously created in the task; note that the document format is displayed after the step name

About the Main Tab

Use the Main tab to define the program and any running parameters for this step.

The tab contains the items listed below.

• Select program to run — Provide the full path and filename of the program. At the time of writing, using remote programs is not supported.
  NOTE: When defining pathnames to executables or files, ensure that the string is enclosed within double quotes, for example "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe". This also applies to any strings used for parameter information.
• Parameters — These are the parameters used by the program defined previously:
  • Name — The parameter name in human-readable form (read-only).
  • Type — The data type of the parameter. At the time of writing, only BSTR (basic string) is supported.
  • Value — The parameter value. You can either manually enter a value or drag-and-drop fields and properties from the Task Browser.
• Add — Use to add a new parameter Name.
• Remove — Removes the highlighted parameter.
• Up and Down Arrows — Re-orders the parameters as required. Each parameters is “called” in the order specified.
• Memory — Use Memory to memorise some or all of the step output for use in other task steps. This is particularly useful when the Run External Program step is called multiple times — use Memory to compare the record previously processed to the new record currently being processed to avoid duplicates.

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

Enabling Wait for program to finish forces the step to not complete until one of the following conditions have been met:

• Indefinitely — The step waits until notified by the program that is has finished before continuing itself
• for a maximum of: — Select this option to enter a maximum time period to wait
  • If the program is still running after this time, fail — If required, select this option to fail the execution after the above time period has expired

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).

If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task).