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 ed6eb5b0799521f87d698db40a7d5bea9045ac96
Author: Alex Heneveld <a...@cloudsoft.io>
AuthorDate: Fri May 19 15:06:19 2023 +0100
update-children first stab at docs
(still to be implemented)
---
guide/blueprints/workflow/steps/steps.yaml | 54 ++++++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
diff --git a/guide/blueprints/workflow/steps/steps.yaml
b/guide/blueprints/workflow/steps/steps.yaml
index 2becd7d6..e6b03c72 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -458,6 +458,60 @@
* `entity`: the entity or entity ID where the adjunct should be
removed, defaulting to the current entity
output: the output from the previous step, or null if this is the first
step
+ - name: update-children
+ # TODO would `synchronize-children` be a better name, or something else?
+ summary: Updates children of an entity to be in 1:1 correspondence with
items in a given list
+ shorthand: '`update-children [of PARENT] blueprint BLUEPRINT id
IDENTIFIER from ITEMS`'
+ input: |
+ * `blueprint`: a blueprint or name of a registered entity type to use
to create the children;
+ this is required unless `on_create` is specified; where supplied as
a blueprint (not a string)
+ the variable `item` can be referenced to provide initial values, but
note this is not updated
+ * `identifier`: an expression in terms of a local variable `item` to
use to identify the same child;
+ e.g. if the `items` is of the form `[{ field_id: ticket1, name:
"Ticket 1" },...]` then
+ and `identifier: ${item.field_id}` will create/update/delete a child
whose ID is `ticket1`;
+ ignored unless `item_check_workflow` is specified
+ * `items`: the list of items to be used to create/update/delete the
children
+ * `parent`: the entity or entity ID whose children are to be updated,
defaulting to the current entity;
+ any children which do not match something in `items` may be removed
+
+ * `on_create`: an optionally supplied workflow to run at any newly
created child, where no pre-existing child was found
+ corresponding to an item in `items` and `update-children` created it
from `blueprint`,
+ passed the `item` (and all inputs to the `update-children` step)
+ and typically doing initial setup as required on the child;
+ the default behavior is to invoke an `on_create` effector at the
child (if there is such an effector, otherwise do nothing), passing `item`;
+ this is invoked prior to `on_update` so if there is nothing special
needed for creation this can be omitted
+
+ * `on_update`: a workflow to run on each child which has a
corresponding item,
+ passed the `item` (and all inputs to the `update-children` step),
+ and typically updating config and sensors as appropriate on the
child;
+ the default behavior is to invoke an `on_update` effector at the
child (if there is such an effector, otherwise do nothing), passing `item`;
+ 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_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)
+
+ * `item_check`:
+ this optionally supplied workflow will be invoked for each item in
`items`
+ to customize the discovery of existing children and/or the creation
of new children;
+ the workflow is passed input variable `item` (and all inputs to the
`update-children` step)
+ and should check whether there is an existing child of `parent` that
matches the `item`;
+ if there is a match that should be updated, this workflow should
return that child,
+ or `null` or `true` if a child should be created, or `false` if the
item should be ignored;
+ following this workflow, the child will be created if necessary
(with `on_create` called),
+ and then have `on_update` called (unless the workflow returned
`false`);
+ the default implementation of this workflow is to compute and return
`${parent.child[${${identifier}}]} ?? true`;
+ this workflow can be used to customize the creation process by
creating and returning a new child (or false)
+
+ * `deletion_check`:
+ this optionally supplied workflow will be invoked for each
pre-existing child which was not
+ returned by the `item_check_workflow`,
+ with each such entity passed as an input variable `child` (along
with all inputs to the `update-children` step);
+ it can then return `true` or `false` to specify whether the child
should be deleted
+ (with `on_delete` called prior to deletion if `true` is returned)
+
+ output: the output from the previous step, or null if this is the first
step
+
-
section_name: General Purpose
section_intro: |
