Hop Run

Hop Run is a command line tool to run your workflows and pipelines.

Hop Run can be launched through the script with the corresponding name in your Hop installation directory, either hop-run.sh on Mac and Linux or hop-run.bat on Windows.

Except for the laucher script, all options are platform agnostic; there is no difference in the way hop-run works on any operating system.

Hop Run Options

You can display Hop Run’s options by running the command without any options.

On Windows, run hop-run.bat. The command on Mac and Linux is hop-run.sh.

You’ll see the option listed in a similar output to the one below:

Usage

Output of help

Usage: <main class> [-ho] [-e=<environmentOption>] [-f=<filename>]
                    [-j=<projectOption>] [-l=<level>]
                    [-r=<runConfigurationName>] [-ps=<parametersSeparator] [-p=<parameters>[,
                    <parameters>...]]... [-s=<systemProperties>[,
                    <systemProperties>...]]...
  -a, --startaction=<startActionName>
                          The name of the action where to start a workflow
  -e, --environment=<environmentOption>
                          The name of the lifecycle environment to use
  -f, --file=<filename>   The filename of the workflow or pipeline to run
  -h, --help              Displays this help message and quits
  -j, --project=<projectOption>
                          The name of the project to use
  -l, --level=<level>     The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL
  -l, --level=<level>     The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL
  -lf, --logfile=<logfile-name> The complete filename where hop-run will write the Hop console log
  -m, --metadata-export=<metadataExportFile>
                          A file containing exported metadata in JSON format
  -o, --printoptions      Print the used options
  -p, --parameters=<parameters>[,<parameters>...]
                          A list of PARAMETER=VALUE pairs
  -ps, --parameters-separator=<parametersSeparator>
                          A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ",").
  -r, --runconfig=<runConfigurationName>
                          The name of the Run Configuration to use
  -s, --system-properties=<systemProperties>[,<systemProperties>...]
                          A comma separated list of KEY=VALUE pairs
  -v, --version           Print version information and exit

The available options are listed in more detail in the table below:

Short Extended Description

Short	Extended	Description
`-e`	`--environment`	The name of the environment to use. Check the documentation on environments for more details.
`-a`	`--startaction`	The name of the action where to start a workflow
`-f`	`--file`	The filename of the workflow or pipeline to run
`-h`	`--help`	Displays this help message and quits.
`-j`	`--project`	The name of the project to use when running a pipeline or workflow
`-l`	`--level`	The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL
`-lf`	`--logfile`	The complete filename where hop-run will write the Hop console log
`-m`	`--metadata-export`	A file containing exported metadata in JSON format. See also the metadata export option in Hop Conf
`-o`	`--printoptions`	Print the used options
`-p`	`--parameters`	A comma separated list of PARAMETER=VALUE pairs
`-ps`	`--parameters-separator`	A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ",").
`-r`	`--runconfig`	The name of the Run Configuration to use. Check the documentation on run configurations for more details.
`-s`	`--system-properties`	A comma separated list of KEY=VALUE pairs

-e

--environment

The name of the environment to use.

Check the documentation on environments for more details.

-a

--startaction

The name of the action where to start a workflow

-f

--file

The filename of the workflow or pipeline to run

-h

--help

Displays this help message and quits.

-j

--project

The name of the project to use when running a pipeline or workflow

-l

--level

The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL

-lf

--logfile

The complete filename where hop-run will write the Hop console log

-m

--metadata-export

A file containing exported metadata in JSON format. See also the metadata export option in Hop Conf

-o

--printoptions

Print the used options

-p

--parameters

A comma separated list of PARAMETER=VALUE pairs

-ps

--parameters-separator

A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ",").

-r

--runconfig

The name of the Run Configuration to use. Check the documentation on run configurations for more details.

-s

--system-properties

A comma separated list of KEY=VALUE pairs

Possible exit codes

Hop Run currently finishes with one of four exit codes.

In all cases except 0, check the error logs for more detailed information for your specific error.

Exit code	Error Message	Description
0	None	No error message. Everything worked flawlessly.
1	Error found during execution!	There was an error executing the workflow or pipeline.
2	General error found, something went horribly wrong!	There was a general error that caused Hop Run to fail completely.
9	None	There was an error parsing the provided parameter information. Hop Run shows the syntax summary and exists.

Exit code

Error Message

Description

None

No error message. Everything worked flawlessly.

Error found during execution!

There was an error executing the workflow or pipeline.

General error found, something went horribly wrong!

There was a general error that caused Hop Run to fail completely.

None

There was an error parsing the provided parameter information. Hop Run shows the syntax summary and exists.

Examples

The example below runs the switch-case-basic.hpl pipeline from the samples project through hop-run.

Windows
Linux, macOS

Open a command (CMD) window, change to the directory where you unzipped Apache Hop and run:

hop-run.bat -j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl

Your output will be similar to what is shown below:

"C:\Program Files\Microsoft\jdk-11.0.17.8-hotspot\\bin\java" -classpath lib\core\*;lib\beam\*;lib\swt\win64\*
-Djava.library.path=lib\core;lib\beam "-Xmx2048m" -DHOP_AUDIT_FOLDER=.\audit
-DHOP_PLATFORM_OS=Windows -DHOP_PLATFORM_RUNTIME=Run -DHOP_AUTO_CREATE_CONFIG=Y org.apache.hop.run.HopRun
-j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl
===[Starting HopRun]=========================================================
2022/12/12 14:09:58 - HopRun - Enabling project 'samples'
2022/12/12 14:09:58 - HopRun - Starting pipeline: config/projects/samples/transforms/switch-case-basic.hpl
2022/12/12 14:09:58 - switch-case-basic - Executing this pipeline using the Local Pipeline Engine with run configuration 'local'
2022/12/12 14:09:58 - switch-case-basic - Execution started for pipeline [switch-case-basic]
2022/12/12 14:09:58 - Test Data.0 - Finished processing (I=0, O=0, R=0, W=5, U=0, E=0)
2022/12/12 14:09:58 - Switch id.0 - Finished processing (I=0, O=0, R=5, W=5, U=0, E=0)
2022/12/12 14:09:58 - Output 2.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:09:58 - Output default.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:09:58 - Output 1.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:09:58 - Output 4.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:09:58 - Output 3.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:09:58 - switch-case-basic - Pipeline duration : 0.542 seconds [  0.542" ]

Open a terminal, change to the directory where you unzipped Apache Hop and run:

./hop-run.sh -j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl

Your output will be similar to what is shown below:

2022/12/12 14:06:39 - HopRun - Enabling project 'samples'
2022/12/12 14:06:39 - HopRun - Relative path filename specified: config/projects/samples//transforms/switch-case-basic.hpl
2022/12/12 14:06:39 - HopRun - Starting pipeline: config/projects/samples//transforms/switch-case-basic.hpl
2022/12/12 14:06:39 - switch-case-basic - Executing this pipeline using the Local Pipeline Engine with run configuration 'local'
2022/12/12 14:06:39 - switch-case-basic - Execution started for pipeline [switch-case-basic]
2022/12/12 14:06:39 - Test Data.0 - Finished processing (I=0, O=0, R=0, W=5, U=0, E=0)
2022/12/12 14:06:39 - Switch id.0 - Finished processing (I=0, O=0, R=5, W=5, U=0, E=0)
2022/12/12 14:06:39 - Output 2.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:06:39 - Output default.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:06:39 - Output 4.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:06:39 - Output 3.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:06:39 - Output 1.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0)
2022/12/12 14:06:39 - switch-case-basic - Pipeline duration : 0.499 seconds [  0.499" ]

Parameter Examples

This is a list of examples on how the parameters on this command are parsed

Normal Usage

--parameters=key1=value1,key2=value2

Result:

Key	value
key1	value1
key2	value2

Key

value

key1

value1

key2

value2

Spaces in value Usage

--parameters=key1="This value contains spaces",key2=value2

Result:

Key	value
key1	This value contains spaces
key2	value2

Key

value

key1

This value contains spaces

key2

value2

Commas in value Usage

--parameters=key1=\"value1,value2\"

Result:

Key	value
key1	value1,value2

Forcing quotes in value

--parameters=key1="\"\"String with spaces\"\""

Result:

Key	value
key1	"String with spaces"