////
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.
////
[[HopRun]]
:imagesdir: ../assets/images
:description: 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

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:

&nbsp; +

.Usage
[%collapsible]
=====

.Output of help
[source,bash]
----
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:

[options="header"]
|===
|Short|Extended a|Description
|```-e```
|```--environment```
|The name of the environment to use.

Check the xref:projects/projects-environments.adoc[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 xref:hop-tools/hop-conf/hop-conf.adoc[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 xref:pipeline/pipeline-run-configurations/pipeline-run-configurations.adoc[documentation on run configurations] for more details.

|```-s```
|```--system-properties```
|A comma separated list of KEY=VALUE pairs
|===

=====

&nbsp; +

== 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. 

[%header, width="90%", cols="1,3,5"]
|===
|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.
|===


== Examples

The example below runs the `switch-case-basic.hpl` pipeline from the samples project through `hop-run`. +
&nbsp; +

[tabs]
====
Windows::
+
--
Open a command (CMD) window, change to the directory where you unzipped Apache Hop and run:

[code, shell]
----
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:

[code, shell]
----
"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" ]
----

--

Linux, macOS::
+
--

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

[code, shell]
----
./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:

[code, shell]
----
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:
[options="header"]
|===
|Key|value
|key1|value1
|key2|value2
|===
==== Spaces in value Usage
----
--parameters=key1="This value contains spaces",key2=value2
----
Result:
[options="header"]
|===
|Key|value
|key1|This value contains spaces
|key2|value2
|===

==== Commas in value Usage
----
--parameters=key1=\"value1,value2\"
----
Result:
[options="header"]
|===
|Key|value
|key1|value1,value2
|===
==== Forcing quotes in value
----
--parameters=key1="\"\"String with spaces\"\""
----
Result:
[options="header"]
|===
|Key|value
|key1|"String with spaces"
|===
