Merge branch 'master' of github.com:apache/brooklyn-docs
diff --git a/guide/blueprints/workflow/settings.md b/guide/blueprints/workflow/settings.md
index ab7af87..c9d409c 100644
--- a/guide/blueprints/workflow/settings.md
+++ b/guide/blueprints/workflow/settings.md
@@ -359,7 +359,9 @@
Where not explicitly set, a system-wide retention default is used. This can be configured in `brooklyn.properties` using
the key `workflow.retention.default`. If no supplied, Brooklyn defaults to `3`, meaning it will keep the three most
-recent invocations of a workflow, with no time limit, and
+recent invocations of a workflow, with no time limit.
+
+Workflows may be kept in-memory for a longer period than persisted to disk, depending on the memory available. This allows, for example, `disabled` and `0` to be indicated to minimize persistence requirements, while maintaining UI and API access to workflow state "softly", that is to say if memory permits. The key `workflow.retention.default.soft` can be configured in `brooklyn.properties` to override the default limit of such workflows kept in memory, from the default value of `3`, or the expression `soft <soft_retention_value>` can be used as part of a retention expression, typically at the end, to customize it per-workflow. If the soft limit is less than or the same as the standard limit there is no apparent effect, as workflow state can be retrieved from in-memory or on-disk. Active workflows are always kept in memory.
Workflow retention is done on a per-entity basis based by default on a hash of the workflow name. Typically workflow
definitions for effectors, sensors, and policies all get unique names for that definition, so the retention applies
@@ -398,6 +400,8 @@
* `max` means completed workflow instances must be retained if they meet any of the constraints implied by
the `<value>` arguments, i.e. `max(2, 3, 1h, 2h)` means to keep the 3 most recent instances irrespective of when
they run, and to keep all instances for up to two hours
+* `<value> soft <soft_value>` where `<soft_value>` can be any of the above, to specify an explicit in-memory soft-retention limit, and `<value>` is any retention expression indicating the normal on-disk retention (where `<value>` must not indicate an additional `soft` or `hard` expression)
+* `<value> hard` as per `soft` but indicating that the `<value>` is both the on-disk and in-memory limit
* `disabled`, to prevent persistence of a workflow, causing less work for the system where workflows don't need to be
stored; such workflows will not be replayable by an operator or recoverable on failover;
this should not be used with workflows that acquire a `lock` unless the entity has special handlers to clear locks
diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index 9cb3aae..f55141b 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -567,6 +567,8 @@
the default behavior is to invoke an `on_update` effector at the child (if there is such an effector, otherwise do nothing);
if the name or any policies may need to change on update, that should be considered in this workflow;
if the `update-children` is performed frequently, it might be efficient in this method to check whether the `item` has changed
+ * `on_update_child`: as `on_update`, but run in the context of the `child` entity for easier configuration there,
+ still with access to `item` and `index`
* `on_delete`: a workflow to run on each child which no longer has a corresponding item prior to its being deleted;
the default behavior is to invoke an `on_delete` effector at the child (if there is such an effector, or nothing);
