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
commit b5099d012e30a007dd5dbff5fcd8ad9ce4014ed3 Author: Alex Heneveld <[email protected]> AuthorDate: Tue Mar 21 16:11:00 2023 +0000 add docs for interpolation_{mode,error}, and docs for retry limit exceeded --- guide/blueprints/workflow/steps/steps.yaml | 15 +++++++++++++-- guide/blueprints/workflow/variables.md | 8 ++++++-- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml index 8360d37d..5bf117f3 100644 --- a/guide/blueprints/workflow/steps/steps.yaml +++ b/guide/blueprints/workflow/steps/steps.yaml @@ -34,6 +34,11 @@ the special types `yaml` and `json` can be specified here to force conversion to a valid YAML or JSON string; the `name` here can be of the form `x.key` where `x` is an existing map variable, to set a specific `key` within it * `value`: the value to set, with some limited evaluation as described [here](../variables.html) + * `interpolation_mode`: whether to run interpolation, defaulting to `words` for shorthand or `full` if `value` is specified in a map; + options are to run on the `full` value (not touching quotes), on `words` (unquoting words, and interpolating only if unquoted), + or `disabled` (to prevent interpolation in the evaluation of this variable) + * `interpolation_errors`: whether unresolvable interpolated expressions `fail` and return an error (the default), or to `ignore` + them (leaving them in their interpolated form), or to replace them with a `blank` string output: the output from the previous step, or null if this is the first step - name: transform @@ -109,6 +114,10 @@ to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`) * `url`: the URL to load * `charset`: the charset to use to process the input + * `interpolation_mode`: whether to evaluated interpolated expressions in the content; default `disabled`; options are as for `let` + * `interpolation_errors`: how to handle errors in interpolated expressions, if `interpolation_mode` is set; + the default `ignore` will leave unresolveable expressions in their expression form which is useful for scripts and other templating systems; + options are as for `let` output: | the output from the previous step or null if this is the first step @@ -133,8 +142,10 @@ if `replay` is specified without next, the default `next` is the `last` replay point (always excluding the retry step itself, even if it is a valid replay point) * `limit`: a list of limit definitions, e.g. `[ "10", "1h", "2 in 1 min" ]` to restrict to a max of 10 retries total, - an additional limit of 2 in any 1 minute period, and an additional limit of 1 hour; the retry will fail if any of these are exceeded; - as shorthand, per the syntax above, it takes one such limit definition + an additional limit of 2 in any 1 minute period, and an additional limit of 1 hour; + as shorthand, per the syntax above, it takes one such limit definition; + the retry will fail with a `RetriesExceededException` if any of these are exceeded; + if it is intended to continue, it is necessary to attach an error handler to the retry step * `backoff`: a specification of how to delay, of the form `INITIAL [ "increasing" FACTOR ] [ "jitter" JITTER ] [ "up to" MAX ]`, where `INITIAL` is one or more durations applied to the respective iteration, and the last value applying to all unless an `increasing FACTOR` is supplied; diff --git a/guide/blueprints/workflow/variables.md b/guide/blueprints/workflow/variables.md index 330b2475..5b865cc5 100644 --- a/guide/blueprints/workflow/variables.md +++ b/guide/blueprints/workflow/variables.md @@ -200,8 +200,8 @@ and the modulo operator `%` for integers giving the remainder. These are evaluated in usual mathematical order. Parentheses are not supported. -The `let` step also supports a `trim` property (or keyword `trimmed` as the first word after the step type) -to indicate that if the value is a string, it should be "trimmed" before setting into the variable. +The `transform` step can be used for more complicated transformations, such as whether to `wait` on values that are not yet ready, +conversion using `json` and `yaml`, and whether to `trim` strings or yaml documents. This supports two types of trimming: if a `type` is specified, the value is scanned for `---` on a line by itself and that token is used as a "document separator", and only the last document is considered; if no `type` is specified, the value has leading and trailing whitespace removed. @@ -256,6 +256,7 @@ The `let` step has some special behavior. It can accept `yaml` and, when convert will strip everything before a `---` document separator. Thus a script can have any output, so long as it ends with `---\n` followed the YAML to read in, then `let yaml fancy-bean = ${stdout}` will convert it to a registered type `fancy-bean`. It will be an error if `stdout` is not coercible to `fancy-bean`. +For more conversion, see `transform`. Another special behavior of `let` is that its `value` is reprocessed, supporting arithmetic as described elsewhere, and also unwrapping quoted words in the value (removing quotes) _without_ evaluating expressions within them. @@ -274,6 +275,9 @@ or a hybrid syntax `{ step: set-sensor x, value: value }`, which can be useful for complex types and bypassing the shorthand processor's unquoting strategy, but in this case note that YAML processing will unwrap quotes. +The `interpolation_mode` and `interpolation_errors` options can be used to specify other +behavior for interpolation, both on `let` and on `load` of data from a URL. + ### Advanced Details
