////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
:documentationPath: /workflow/actions/
:openvar: ${
:closevar: }
:language: en_US
:description: The Shell action executes a shell script on the host where the workflow is running.

= 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 provided by the operating system call.

For example, in batch scripting a return value of 1 indicates that the script was successful; a return value of 0 (zero) indicates that it was unsuccessful.

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

== Options

=== General tab

[options="header", width="90%". cols="1,3"]
|===
|Option|Description
|Action name|The name of the workflow action.
|Insert script a|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.

NOTE: Variables are resolved within the script when given.
|Script file name|The filename of the shell script to start, should include full path else {openvar}user.dir{closevar} 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 {openvar}user.dir{closevar} will be used as working directory.
2+|Logging settings
|Specify log file|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
|Copy previous results to arguments?|The results from a previous pipeline can be sent to the shell script using the "Copy rows to result" transform. (as arguments)
|Execute once for every input 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.
|===

=== Script tab

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