External Program

External Program action tasks are used to launch and execute other programs, which can be useful when you wish to process your job file in a way that is not possible with the standard PlanetPress Workflow tasks.

There are some important things to consider when using the External Program task:

• The executable file must accept so-called "command-line options" and be able to run without any sort of user interaction. Only certain programs are able to do this and may refer to it as "command-line" or "automation" features.
• The process will always wait for the executable file to finish before it continues to the next task, and does not have any timeout setting. This mean that if your program fails to exit for any reason, your process will hang.

Input

Any active data file, in any format.

Processing

The external program is executed using the parameters provided. Note that the current data file is not "sent" to the executable file, however you can refer to the full path of the data file using %F.

Output

If the external program modifies the job file using the full path, the modified file is the output of this software. Otherwise, the output is the same as the input. Metadata is not modified in any way. Job Infos may be modified, depending on the options set in the task's properties.

Task properties

General Tab

• Program group
  • Executable file: Enter the name and path of an executable file (exe or com extension), batch file (bat extension), or command script (cmd extension) that can run in command mode. Note that the program will be run without user interaction. Although it may display progress information, it is better if the application has no user interface.
  • Parameters: Enter parameters that will be passed to the external program when it is launched. Each parameter should be enclosed in quotation marks and separated by a space ("Param1" "Param2" "Param3") except command line options (such as -f, /n). The exact parameters accepted are unique to the executable and defined in its documentation if it exists.
  • Start in: Enter the folder in which the external program is to run. This is important, for example, if the program is to generate files that are to be picked up in a specific location for further processing, or if it requires resources that are located in a specific folder. Leave blank to run the program in the folder of the executable file.
  • Run minimized: Select to prevent a window (a DOS box, for instance) from being displayed on the desktop. When selected, the program runs in a background window.
• Program output capture group
  • Log the program output: Check to store the program output (messages generated by the execution of the external program) inside of a job info or variable.
  • Store the program output in variable: Use the drop-down to select which variable or job info to will be used to store the program output.
• Exit Code group
  • Store the exit code in job info: Use the drop-down to select which variable or job info will be used to store the program's exit code. The exit code is a numerical value generated by the program which will indicate whether its execution was a success or if errors were encountered.
  • Verify return value: Check to enable the group and react whenever specific exit codes are returned by the software.
  • If exit code is: Use the drop-down to select how to compare to the exit code. This numerical comparison is either equal, greater than or lower than.
  • Value: The numerical exit code that will be verified.
  • Return: Use the drop-down to select whether this exit code should define a success or a failure of the external program. If "Failure" is chosen, exit codes that match the condition set will cause the On Error tab to be triggered and any other exit code will be considered a success. Inversily, if Success is chosen, exit codes that match the condition set will cause be considered a success and any other exit code will cause the On Error tab to be triggered.

On Error Tab

For a description of the options on the On Error tab see Using the On Error tab.

Miscellaneous Tab

The Miscellaneous tab is common to all tasks.

It contains a text area (Task comments) that lets you write comments about the task. These comments are saved when the dialog is closed with the OK button and are displayed in the Task Comments Pane.

Check the option Use as step description to display the text next to the icon of the plugin in the Process area.

The tab also provides an option to highlight the task in The Process area with the default color, set in the Preferences (see General appearance preferences), or the color selected or defined under Highlight color on this tab.
To revert the selected highlight color to the default color, open this tab, turn the Highlight option off and close the dialog with the OK button; then turn highlighting back on.
Highlighting can also be turned on and off via the task's contextual menu and with the Highlight button on the View ribbon.