This is an automated email from the ASF dual-hosted git repository.
heneveld pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
The following commit(s) were added to refs/heads/master by this push:
new ba16478c add docs for 'if' and 'foreach ... do'
ba16478c is described below
commit ba16478cbf27f65d3b47f3649dacf16405cddbd9
Author: Alex Heneveld <a...@cloudsoft.io>
AuthorDate: Mon Feb 26 13:17:12 2024 +0000
add docs for 'if' and 'foreach ... do'
---
guide/blueprints/workflow/common.md | 15 +++++++
guide/blueprints/workflow/nested-workflow.md | 59 +++++++++++++++++++++++++---
guide/blueprints/workflow/steps/steps.yaml | 18 +++++++--
3 files changed, 84 insertions(+), 8 deletions(-)
diff --git a/guide/blueprints/workflow/common.md
b/guide/blueprints/workflow/common.md
index 910a5324..a2ad6e05 100644
--- a/guide/blueprints/workflow/common.md
+++ b/guide/blueprints/workflow/common.md
@@ -91,6 +91,8 @@ the workflow moves to the following step in the sequence, or
ends if that was th
Apart from `name` and `id` above, if a step's `condition` is unmet,
the other properties set on a step are ignored.
+The `if` step can be used for simple conditions, as shown in the next section.
+
### Jumping with "Next" or "Goto"
@@ -115,6 +117,19 @@ and its availability not abused: in particular where a
task can be better done
in a proper high-level programming language, consider putting that program
into a container and calling it from your workflow.
+Thus the above workflow can be written more concisely as:
+
+```
+steps:
+- if ${scratch.skip_date} then goto skipping-ssh-date
+
+- step: ssh echo today is `date`
+ next: end
+
+- id: skipping-ssh-date
+ name: Not doing SSH
+ step: log skipping ssh date command
+```
### Input and Output
diff --git a/guide/blueprints/workflow/nested-workflow.md
b/guide/blueprints/workflow/nested-workflow.md
index ea95a74c..c8c8eed2 100644
--- a/guide/blueprints/workflow/nested-workflow.md
+++ b/guide/blueprints/workflow/nested-workflow.md
@@ -74,7 +74,9 @@ An example of this is included below, using `service.isUp`
with `children`.
The `foreach` type is a simplified variant of `workflow` when recursing over a
list,
taking the same arguments as `workflow` but supporting a shorthand syntax where
the `target_var_name` and `target` can be specified as in `foreach VAR_NAME in
TARGET`.
-The `steps` are required and are run for all elements in the list.
+A single step can be supplied as `do STEP` at the end;
+either that or `steps` is required (but not both),
+and that step or those steps are run for all items in the target list.
The `subworkflow` type is another simplified variant that does not allow any
target
(so no recursing over a list and no concurrency), and which -- unlike the
other workflow step types --
@@ -85,16 +87,65 @@ A `name` is frequently given for readability, as are
`condition` or `on-error` e
to apply a condition or error-handler to the block of steps.
If no step type is defined, but `steps` are defined, this `subworkflow` step
type is assumed.
+The `if` type acts like `subworkflow` but allows specifying a condition in
shorthand.
+
#### Example
```
+- foreach x in 1..3 do return ${x}
+```
+
+The above loop will return `[1,2,3]` and proceed to the next step.
+
+```
+# foreach, nested workflow
- step: foreach x in 1..3
steps:
+ - let x = ${x} + 1
- return ${x}
```
-The above loop will return `[1,2,3]`.
+The above loop will return `[2,3,4]` and proceed to the next step.
+It is the same as the previous except it is supplying multiple steps
+to run on each iteration.
+Note that the assignment to `${x}` does not side-effect the loop,
+and nor is it available to the outer workflow, when using `foreach` or
`workflow`.
+Use `${output}` to access the result,
+and see the `reducing` section below.
+
+```
+# subworkflow
+- let x = 1
+- steps:
+ - let x = ${x} + 1
+ - return ${x}
+- let x = Not run, but if it were it could access ${x}
+```
+
+The above implicit lightweight subworkflow _does_ run in the parent workflow's
context,
+so it will access and update the same instance of `${x}`,
+and it will `return` from the workflow, not running the next step.
+
+```
+# if
+- let x = 1
+- if ${x} == 1 then let x = ${x} + 1
+- return ${x}
+```
+
+The above `if` step can access and update outer variables, like `subworkflow`,
providing a convenient shorthand for simple conditions and steps. It is
functionally identical to this:
+
+```
+- let x = 1
+- condition:
+ target: ${x}
+ equals: 1
+ steps:
+ - let x = ${x} + 1
+- return ${x}
+```
+
### Reducing
@@ -114,11 +165,9 @@ and it cannot be used with `concurrency` as that risks
race conditions in updati
#### Example
```
-- step: foreach x in 1..3
+- step: foreach x in 1..3 do let sum = ${sum} + ${x}
reducing:
sum: 0
- steps:
- - let sum = ${sum} + ${x}
```
The above loop will return `6`.
diff --git a/guide/blueprints/workflow/steps/steps.yaml
b/guide/blueprints/workflow/steps/steps.yaml
index ef4e9761..c636b05a 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -104,6 +104,16 @@
* `value`: the value to return
output: the value indicated
+ - name: if
+ summary: |
+ Provides shorthand for a simple condition and step.
+ shorthand: '`${condition_target} [ "==" ${condition_equals} ] [ " then "
${step...} ]`'
+ input: |
+ * `condition_target`: a condition to evaluate or an expression to
check (for truthiness, unless a condition_equals is supplied)
+ * `condition_equals`: a value to compare for equality against the
supplied condition_target (which should not be a condition if this is used)
+ * `step` or `steps`: a subworkflow to run if the condition passes
+ output: the result of the supplied step or steps
+
- name: wait
summary: |
Waits for a value which might not yet be resolved, or a task which
might not have finished,
@@ -234,10 +244,12 @@
input: |
- name: foreach
- summary: Runs nested workflow over a list using the specified variable
name, equivalent to `workflow` when looping over a list
- shorthand: '`foreach TARGET_VAR_NAME [ in TARGET ]`'
+ summary: |
+ Runs nested workflow over a list using the specified variable name,
equivalent to `workflow` when looping over a list,
+ with support for including a single step as shorthand
+ shorthand: '`foreach TARGET_VAR_NAME [ in TARGET [ do STEP ]]`'
input: |
- * `steps`: a list of steps to run, run in a separate context
+ * `step` or `steps`: a list of steps to run, run in a separate context
* `target_var_name`: the name of the variable that should be set in
nested workflows to refer to the element in the target list,
with the additional behavior that if this is of the "spread map
syntax" form `{KEY,KEY2}`, each element in the target list will be assumed to
be a map
and the keys "KEY" and "KEY2" will be extracted and each one set as
a variable in the nested workflow
