apache · hansva · Mar 15, 2023 · Mar 14, 2023
diff --git a/docs/hop-user-manual/modules/ROOT/assets/images/metadata-types/workflow-log.png b/docs/hop-user-manual/modules/ROOT/assets/images/metadata-types/workflow-log.png
diff --git a/docs/hop-user-manual/modules/ROOT/nav.adoc b/docs/hop-user-manual/modules/ROOT/nav.adoc
@@ -257,6 +257,7 @@ under the License.
 *** xref:pipeline/transforms/verticabulkloader.adoc[Vertica Bulk Loader]
 *** xref:pipeline/transforms/webservices.adoc[Web services lookup]
 *** xref:pipeline/transforms/workflowexecutor.adoc[Workflow Executor]
+*** xref:pipeline/transforms/workflow-logging.adoc[Workflow Logging]
 *** xref:pipeline/transforms/writetolog.adoc[Write to log]
 *** xref:pipeline/transforms/xmlinputstream.adoc[XML Input Stream (StAX)]
 *** xref:pipeline/transforms/xmljoin.adoc[XML Join]

diff --git a/docs/hop-user-manual/modules/ROOT/pages/metadata-types/pipeline-log.adoc b/docs/hop-user-manual/modules/ROOT/pages/metadata-types/pipeline-log.adoc
@@ -60,6 +60,3 @@ image:metadata-types/pipeline-log.png[Pipeline Log, width="75%"]
 |Interval in seconds|30|if executed periodically, indicates the interval at which the pipeline log is executed
 |===
 
-== Samples
-
-None
diff --git a/docs/hop-user-manual/modules/ROOT/pages/metadata-types/workflow-log.adoc b/docs/hop-user-manual/modules/ROOT/pages/metadata-types/workflow-log.adoc
@@ -17,6 +17,8 @@ under the License.
 :imagesdir: ../../assets/images/
 :page-pagination:
 :description: Allows to log the activity of a workflow with a pipeline. A workflow log streams logging information from a running workflow to a pipeline. This receiving pipeline can then process this logging information and e.g. write to a relational or NoSQL database, a Kafka topic etc
+:openvar: ${
+:closevar: }
 
 = Workflow Log
 
@@ -27,11 +29,21 @@ image:icons/workflow-log.svg[]
 Allows to log the activity of a workflow with a pipeline.
 
 A workflow log streams logging information from a running workflow to a pipeline.
-This receiving pipeline can then process this logging information and e.g. write to a relational or NoSQL database, a Kafka topic etc
+
+The only requirement for the receiving pipeline is that it starts with a xref:pipeline/transforms/workflow-logging.adoc[Workflow Logging] transform. Other than that, the logging pipeline is "just another pipeline".
+In this logging pipeline, you can process the logging information and e.g. write to a relational or NoSQL database, a Kafka topic etc
+
+== Samples
+
+The samples project comes with an example workflow log.
+
+Check the metadata perspective for the workflow log `workflow-log-example`. This workflow log is configured to send logging information for the workflow `{openvar}PROJECT_HOME{closevar}/reflection/generate-fake-books.hwf` to the logging pipeline `{openvar}PROJECT_HOME{closevar}/reflection/workflow-log-example.hpl`.
+
+image:metadata-types/workflow-log.png[Workflow Log, width="75%"]
 
 == Related Plugins
 
-* Workflow Logging
+* xref:pipeline/transforms/workflow-logging.adoc[Workflow Logging]
 
 == Options
 
@@ -48,6 +60,3 @@ This receiving pipeline can then process this logging information and e.g. write
 |Interval in seconds|30|if executed periodically, indicates the interval at which the workflow log is executed
 |===
 
-== Samples
-
-None
diff --git a/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms.adoc b/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms.adoc
@@ -210,6 +210,7 @@ The pages nested under this topic contain information on how to use the transfor
 * xref:pipeline/transforms/valuemapper.adoc[Value Mapper]
 * xref:pipeline/transforms/webservices.adoc[Web services lookup]
 * xref:pipeline/transforms/workflowexecutor.adoc[Workflow Executor]
+* xref:pipeline/transforms/workflow-logging.adoc[Workflow Logging]
 * xref:pipeline/transforms/writetolog.adoc[Write to log]
 * xref:pipeline/transforms/xmlinputstream.adoc[XML Input Stream (StAX)]
 * xref:pipeline/transforms/xmljoin.adoc[XML Join]

diff --git a/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/pipeline-logging.adoc b/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/pipeline-logging.adoc
@@ -17,15 +17,32 @@ under the License.
 :imagesdir: ../../assets/images/
 :page-pagination:
 :description: The pipeline logging transform gives you detailed logging information about a pipeline and its transforms.
+:openvar: ${
+:closevar: }
 
-= Pipeline Logging
+= image:icons/pipeline-log.svg[Pipeline logging transform Icon, role="image-doc-icon"] Pipeline Logging
 
+[%noheader,cols="3a,1a", role="table-no-borders" ]
+|===
+|
 == Description
 
 the Pipeline Logging transform receives its input from a xref:metadata-types/pipeline-log.adoc[Pipeline Log] metadata item.
 
 The transform requires very little configuration, but provides a lot of information.
 
+
+|
+== Supported Engines
+[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
+!===
+!Hop Engine! image:check_mark.svg[Supported, 24]
+!Spark! image:question_mark.svg[Maybe Supported, 24]
+!Flink! image:question_mark.svg[Maybe Supported, 24]
+!Dataflow! image:question_mark.svg[Maybe Supported, 24]
+!===
+|===
+
 == Related Plugins
 
 * xref:metadata-types/pipeline-log.adoc[Pipeline Log]

diff --git a/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/workflow-logging.adoc b/docs/hop-user-manual/modules/ROOT/pages/pipeline/transforms/workflow-logging.adoc
@@ -0,0 +1,94 @@
+////
+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.
+////
+:imagesdir: ../../assets/images/
+:page-pagination:
+:description: The workflow logging transform gives you detailed logging information about a workflow and its actions.
+:openvar: ${
+:closevar: }
+
+= image:icons/workflow-log.svg[Workflow logging transform Icon, role="image-doc-icon"] Workflow logging
+
+
+[%noheader,cols="3a,1a", role="table-no-borders" ]
+|===
+|
+== Description
+
+the Workflow Logging transform receives its input from a xref:metadata-types/workflow-log.adoc[Workflow Log] metadata item.
+
+The transform requires very little configuration, but provides a lot of information.
+
+|
+== Supported Engines
+[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
+!===
+!Hop Engine! image:check_mark.svg[Supported, 24]
+!Spark! image:question_mark.svg[Maybe Supported, 24]
+!Flink! image:question_mark.svg[Maybe Supported, 24]
+!Dataflow! image:question_mark.svg[Maybe Supported, 24]
+!===
+|===
+
+== Related Plugins
+
+* xref:metadata-types/workflow-log.adoc[Workflow Log]
+
+== Options
+
+[%header, width="90%", cols="1,5"]
+|===
+|Option|Description
+|Transform name|Name of this transform
+|Also log action details a|
+
+* checked: the transform outputs both workflow and action logging and metrics. In this case, the logging will contain one line per action. For each action, the workflow logging and metrics information is repeated.
+* unchecked: the transform only outputs workflow logging and metrics.
+|===
+
+== Output Fields
+
+[%header, width="90%", cols="1,1,5"]
+|===
+ |Fieldname|Type|Description
+3+|**Workflow Logging Fields**
+|loggingDate|Date|the date and time this workflow was executed
+|loggingPhase|String|the phase this workflow is in at the time of logging (e.g. 'end')
+|workflowName|String|the logged workflow name
+|workflowFilename|String|the logged workflow file name
+|workflowStart|Date|execution start date for the logged workflow
+|workflowEnd|Date|execution end date for the logged workflow
+|workflowLogChannelId|String|logging channel id for the logged workflow
+|parentLogChannelId|String|parent logging channel id for the logged workflow (e.g. the channel id of the parent workflow)
+|workflowLogging|String|full logging text for the logged workflow
+|workflowErrorCount|Integer|number of errors that occurred in the logged workflow execution
+|workflowStatusDescription|String|status description for the logged workflow (e.g. 'Finished')
+3+|**Action Logging Fields**
+|actionName|String|the name of the action in the logged pipeline
+|actionNr|Integer|the number of the current action
+|actionResult|the result (exit code, Y/N) of the current action
+|actionLogChannelId|String|log channel id for the current action
+|actionLoggingText|String|logging text for the current action
+|actionErrors|Integer|number of errors for the current action
+|actionLogDate|String|status of the current action (e.g. 'Finished')
+|actionDuration|Integer|total duration for the current action
+|actionExitStatus|exit status of the current action
+|actionNrFilesRetrieved|the number of files retrieved by the current transform (if applicable)
+|actionFilename|the filename to use for the current action, e.g. the workflow or pipeline the current action runs.
+|actionComment|an optional comment added to the logs, e.g. `Workflow execution finished`
+|actionReason|an optional reason provided by the current action
+|===
+
diff --git a/...ction/src/main/java/org/apache/hop/reflection/workflow/transform/WorkflowLoggingMeta.java b/...ction/src/main/java/org/apache/hop/reflection/workflow/transform/WorkflowLoggingMeta.java
@@ -36,7 +36,7 @@
     name = "i18n::WorkflowLogging.Transform.Name",
     description = "i18n::WorkflowLogging.Transform.Description",
     categoryDescription = "i18n:org.apache.hop.pipeline.transform:BaseTransform.Category.Input",
-    documentationUrl = "/logging/logging-reflection.html",
+    documentationUrl = "/pipeline/transforms/pipeline-logging.html",
     image = "workflow-log.svg",
     keywords = "i18n::WorkflowLoggingMeta.keyword")
 public class WorkflowLoggingMeta extends BaseTransformMeta<WorkflowLogging, WorkflowLoggingData> {

diff --git a/plugins/misc/reflection/src/main/samples/metadata/workflow-log/workflow-log-example.json b/plugins/misc/reflection/src/main/samples/metadata/workflow-log/workflow-log-example.json
@@ -0,0 +1,13 @@
+{
+  "loggingParentsOnly": true,
+  "name": "workflow-log-example",
+  "workflowToLog": [
+    "${PROJECT_HOME}/reflection/generate-fake-books.hwf"
+  ],
+  "intervalInSeconds": "30",
+  "executingPeriodically": false,
+  "pipelineFilename": "${PROJECT_HOME}/reflection/workflow-log-example.hpl",
+  "executingAtEnd": true,
+  "enabled": true,
+  "executingAtStart": true
+}
diff --git a/plugins/misc/reflection/src/main/samples/reflection/generate-fake-books.hwf b/plugins/misc/reflection/src/main/samples/reflection/generate-fake-books.hwf
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+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.
+
+-->
+<workflow>
+  <name>generate-fake-books</name>
+  <name_sync_with_filename>Y</name_sync_with_filename>
+  <description/>
+  <extended_description/>
+  <workflow_version/>
+  <created_user>-</created_user>
+  <created_date>2023/03/14 19:32:36.099</created_date>
+  <modified_user>-</modified_user>
+  <modified_date>2023/03/14 19:32:36.099</modified_date>
+  <parameters>
+    </parameters>
+  <actions>
+    <action>
+      <name>Start</name>
+      <description/>
+      <type>SPECIAL</type>
+      <attributes/>
+      <DayOfMonth>1</DayOfMonth>
+      <hour>12</hour>
+      <intervalMinutes>60</intervalMinutes>
+      <intervalSeconds>0</intervalSeconds>
+      <minutes>0</minutes>
+      <repeat>N</repeat>
+      <schedulerType>0</schedulerType>
+      <weekDay>1</weekDay>
+      <parallel>N</parallel>
+      <xloc>50</xloc>
+      <yloc>80</yloc>
+      <attributes_hac/>
+    </action>
+    <action>
+      <name>Pipeline</name>
+      <description/>
+      <type>PIPELINE</type>
+      <attributes/>
+      <filename>${PROJECT_HOME}/reflection/generate-fake-books.hpl</filename>
+      <params_from_previous>N</params_from_previous>
+      <exec_per_row>N</exec_per_row>
+      <clear_rows>N</clear_rows>
+      <clear_files>N</clear_files>
+      <set_logfile>N</set_logfile>
+      <logfile/>
+      <logext/>
+      <add_date>N</add_date>
+      <add_time>N</add_time>
+      <loglevel>Basic</loglevel>
+      <set_append_logfile>N</set_append_logfile>
+      <wait_until_finished>Y</wait_until_finished>
+      <create_parent_folder>N</create_parent_folder>
+      <run_configuration>Spark</run_configuration>
+      <parameters>
+        <pass_all_parameters>Y</pass_all_parameters>
+      </parameters>
+      <parallel>N</parallel>
+      <xloc>209</xloc>
+      <yloc>80</yloc>
+      <attributes_hac/>
+    </action>
+    <action>
+      <name>Write to log</name>
+      <description/>
+      <type>WRITE_TO_LOG</type>
+      <attributes/>
+      <logmessage/>
+      <loglevel/>
+      <logsubject/>
+      <parallel>N</parallel>
+      <xloc>368</xloc>
+      <yloc>80</yloc>
+      <attributes_hac/>
+    </action>
+    <action>
+      <name>Dummy</name>
+      <description/>
+      <type>DUMMY</type>
+      <attributes/>
+      <parallel>N</parallel>
+      <xloc>527</xloc>
+      <yloc>80</yloc>
+      <attributes_hac/>
+    </action>
+  </actions>
+  <hops>
+    <hop>
+      <from>Start</from>
+      <to>Pipeline</to>
+      <enabled>Y</enabled>
+      <evaluation>Y</evaluation>
+      <unconditional>Y</unconditional>
+    </hop>
+    <hop>
+      <from>Pipeline</from>
+      <to>Write to log</to>
+      <enabled>Y</enabled>
+      <evaluation>Y</evaluation>
+      <unconditional>N</unconditional>
+    </hop>
+    <hop>
+      <from>Write to log</from>
+      <to>Dummy</to>
+      <enabled>Y</enabled>
+      <evaluation>Y</evaluation>
+      <unconditional>N</unconditional>
+    </hop>
+  </hops>
+  <notepads>
+    <notepad>
+      <backgroundcolorblue>251</backgroundcolorblue>
+      <backgroundcolorgreen>232</backgroundcolorgreen>
+      <backgroundcolorred>201</backgroundcolorred>
+      <bordercolorblue>90</bordercolorblue>
+      <bordercolorgreen>58</bordercolorgreen>
+      <bordercolorred>14</bordercolorred>
+      <fontbold>N</fontbold>
+      <fontcolorblue>90</fontcolorblue>
+      <fontcolorgreen>58</fontcolorgreen>
+      <fontcolorred>14</fontcolorred>
+      <fontitalic>N</fontitalic>
+      <fontname>Noto Sans</fontname>
+      <fontsize>10</fontsize>
+      <height>27</height>
+      <xloc>48</xloc>
+      <yloc>16</yloc>
+      <note>this workflow doesn't really do anything, it's mainly used to be executed by ${PROJECT_HOME}/reflection/workflow-log-example.hpl</note>
+      <width>729</width>
+    </notepad>
+  </notepads>
+  <attributes/>
+</workflow>
-Original file line number
+Diff line change
@@ Expand Up @@
     |Interval in seconds|30|if executed periodically, indicates the interval at which the pipeline log is executed
     |===
-    == Samples
-    None