Shell

Description

The Shell action executes a shell script on the host where the workflow is running.

For example, suppose you have a program that reads five data tables and creates a file in a specified format.

Scripts or executables

Shell allows you to do portions of your work in Apache Hop but reuse the program that reads the data tables as needed.

The Shell workflow action is platform agnostic; you can use a batch file, UNIX, and so on.

When you use a Shell workflow action, Hop makes a Java call to execute a program in a specified location.

Embedded scripts

As an alternative to calling scripts on the host machine, you can enter scripts (e.g. batch on Windows, shell script on Linux) directly in the Shell action.

Return status

The return status is the exit code of the script or executable. An exit code of 0 means success; any other exit code makes the action fail. See Result.

You can pass command line arguments and set up logging for the Shell workflow action.

Options

General tab

Option

Description

Action name

The name of the workflow action.

Insert script

Check this option when you want to execute the script in the Script tab instead of executing the Script file name. This is also useful, when you want to execute operating system commands like dir, ls or ipconfig without giving a specific path. This option creates a temporary script in the working directory and executes it.

Variables are resolved within the script when given.

Script file name

The filename of the shell script to start, should include full path else ${user.dir} is used as path.

Working directory

The directory that will be used as working directory for the shell script. The working directory only becomes active when the shell script starts so "Filename" should still include the full path to the script. When the field is left empty or the working directory is invalid ${user.dir} will be used as working directory.

Logging settings

Specify logfile

Enable to specify a separate logging file for the execution of this workflow.

Append logfile

Enable to append to the logfile as opposed to creating a new one

Name of log file

The directory and base name of the log file (for example C:\logs)

Extension of the log file

The filename extension (for example: log or txt)

Include date in filename?

Adds the system date to the filename. (_20051231)

Include time in filename?

Adds the system time to the filename. (_235959)

Loglevel

Specifies the logging level for the execution of the shell. See also the logging window in .14 Logging

Arguments tab

Option Description

Option	Description
Copy previous results to args	The results from a previous pipeline can be sent to the shell script using the "Copy rows to result" transform. (as arguments)
Execute for every result row	This implements looping. If the previous workflow action returns a set of result rows, you can have this shell script executed once for every row found. One row is passed to this script at every execution in combination with the copy previous result to arguments. The values of the corresponding result row can then be found on command line argument $1, $2, … (%1, %2, %3, … on Windows)
Arguments table	Specify the strings to use as arguments for the shell script. The Hidden (Y/N) column controls logging only: when set to `Y`, the argument is replaced by `*` in the Shell action log. The script still receives the real value.

Copy previous results to args

The results from a previous pipeline can be sent to the shell script using the "Copy rows to result" transform. (as arguments)

Execute for every result row

This implements looping. If the previous workflow action returns a set of result rows, you can have this shell script executed once for every row found. One row is passed to this script at every execution in combination with the copy previous result to arguments. The values of the corresponding result row can then be found on command line argument $1, $2, … (%1, %2, %3, … on Windows)

Arguments table

Specify the strings to use as arguments for the shell script.

The Hidden (Y/N) column controls logging only: when set to Y, the argument is replaced by * in the Shell action log. The script still receives the real value.

Script tab

This tab contains your batch or shell script if the Insert script option is checked.

Result

What this action passes on to the next action. See Action results for how results travel through a workflow.

Result Value

Result	Value
True	The command ended with exit code 0. With Execute for every result row, every run did.
False	The command ended with another exit code, or could not be started, for example because the script file doesn’t exist on Linux or macOS. On Windows, `cmd.exe` starts anyway and returns a non-zero exit code. The number of errors is 1. With Execute for every result row, the first run that fails ends the loop: the remaining rows are not processed.
Result files	Passed on unchanged, plus the log file with Specify logfile.
Result rows	Passed on unchanged. With Copy previous results to args, the fields of the result rows are passed as arguments: the fields of every row in a single run, or with Execute for every result row the fields of the current row in each run.
Metrics	Exit status: the exit code of the command; with Execute for every result row, of the last run. It is not set when the command could not be started.

True

The command ended with exit code 0. With Execute for every result row, every run did.

False

The command ended with another exit code, or could not be started, for example because the script file doesn’t exist on Linux or macOS. On Windows, cmd.exe starts anyway and returns a non-zero exit code. The number of errors is 1. With Execute for every result row, the first run that fails ends the loop: the remaining rows are not processed.

Result files

Passed on unchanged, plus the log file with Specify logfile.

Result rows

Passed on unchanged. With Copy previous results to args, the fields of the result rows are passed as arguments: the fields of every row in a single run, or with Execute for every result row the fields of the current row in each run.

Metrics

Exit status: the exit code of the command; with Execute for every result row, of the last run. It is not set when the command could not be started.

With Execute for every result row and no result rows, the command doesn’t run, and the result of the previous action is passed on, without an exit status.