This is an automated email from the ASF dual-hosted git repository.
mattcasters pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new 622e9575d4 Document how to run a workflow from another project (#9137)
622e9575d4 is described below
commit 622e9575d4a3ac230e1225c5e53ea0415a7fc0f5
Author: Diogo Esteves <[email protected]>
AuthorDate: Thu Oct 29 09:09:50 2026 +0000
Document how to run a workflow from another project (#9137)
A Workflow or Pipeline action runs a file of another project in the
project and environment of the caller, so the variables in the other
project's environment configuration files are not set. Explain how to
add that file to the caller's environment (Hop Gui or hop-conf), the
replace and order semantics of --environment-config-files, and that
metadata needs a parent project instead. Note in the hop-run options
that -j is ignored when -e is set, and link the section from the
Workflow action page.
Prompted by discussion #9123.
---
.../modules/ROOT/pages/hop-run/index.adoc | 3 ++-
.../ROOT/pages/projects/projects-environments.adoc | 27 ++++++++++++++++++++++
.../ROOT/pages/workflow/actions/workflow.adoc | 1 +
3 files changed, 30 insertions(+), 1 deletion(-)
diff --git a/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
index 902cd998a6..626cac882b 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
@@ -115,7 +115,8 @@ Strict by default — when omitted, Hop Run refuses to start
such a run and prin
|```-j```
|```--project```
|The name of the project to use when running a pipeline or workflow.
-Not needed when `-e` is set.
+Ignored when `-e` is set: the project of that environment is used.
+To use a workflow of another project, see
xref:projects/projects-environments.adoc#_run_a_workflow_from_another_project[Run
a workflow from another project].
|```-l```
|```--level```
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/projects/projects-environments.adoc
b/docs/hop-user-manual/modules/ROOT/pages/projects/projects-environments.adoc
index fb8baf8c59..b736fb25c5 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/projects/projects-environments.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/projects/projects-environments.adoc
@@ -297,5 +297,32 @@ image:hop-gui/environment/edit-environment-menu.png[Edit
environment menu]
* *Duplicate environment...* creates a copy of the selected environment.
* *Delete environment...* removes the environment from the Hop configuration.
+== Run a workflow from another project
+
+`hop-run -e` takes the project from the environment, and the variables from
the configuration files of that environment.
+When `-e` is set, `-j` is ignored.
+
+A xref:workflow/actions/workflow.adoc[Workflow] or
xref:workflow/actions/pipeline.adoc[Pipeline] action that runs a file from
another project runs it in the project and environment of the calling workflow.
+It does not switch to an environment of the other project, so variables that
are only defined in the configuration files of its environments are not set.
+
+To set them, add the configuration file of the other project to the
environment of the calling project.
+In Hop Gui, choose *Edit environment...* and add the file on the
*Configuration files* tab with *Select...*.
+With hop-conf, for example when environment `sales-dev` of project `sales`
runs a workflow of project `crm`:
+
+[source,bash]
+----
+./hop-conf.sh --environment-modify --environment=sales-dev \
+
--environment-config-files=/data/environments/sales-dev/variables.json,/data/environments/crm-dev/variables.json
+----
+
+`--environment-config-files` replaces the whole list, so keep the files the
environment already has: `./hop-conf.sh --environments-list` shows them.
+The files are applied in the order of the list, so when two files set the same
variable, the last one wins.
+To add a file for a single run without changing the environment, pass it to
hop-run with `--environment-conf-files`.
+
+NOTE: This brings the variables of the other project, not its metadata, such
as database connections and run configurations.
+When the workflow needs those as well, set the other project as *Parent
project to inherit from* on the *Parent project* tab of the calling project, or
run `./hop-conf.sh --project-modify --project=sales --project-parent=crm`.
+The calling project then reads the metadata of both projects and the project
variables of the parent, but not the configuration files of the parent's
environments.
+A project has one parent, and also inherits from the parent's own parent.
+
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/workflow.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/workflow.adoc
index 0cfb5d8564..5cff5631a3 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/workflow.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/workflow.adoc
@@ -40,6 +40,7 @@ See also:
* The xref:workflow/actions/pipeline.adoc[Pipeline action] that executes a
pipeline from a workflow.
* The xref:pipeline/transforms/workflow-executor.adoc[Workflow Executor
transform] that executes a workflow from a pipeline.
* The xref:pipeline/transforms/pipeline-executor.adoc[Pipeline Executor
transform] that executes a sub-pipeline from a pipeline.
+*
xref:projects/projects-environments.adoc#_run_a_workflow_from_another_project[Run
a workflow from another project] for the variables and metadata that a
workflow from another project can use.
== Options
