add docs for add'l model-manipulation workflow steps
diff --git a/guide/blueprints/workflow/nested-workflow.md b/guide/blueprints/workflow/nested-workflow.md
index f961a01..fd52ead 100644
--- a/guide/blueprints/workflow/nested-workflow.md
+++ b/guide/blueprints/workflow/nested-workflow.md
@@ -160,3 +160,44 @@
especially with parameters and shorthand templates.
The [examples](examples/) and the [workflow settings](settings.md) include more realistic
illustrations of custom workflow steps.
+
+
+#### Writing Workflow Steps in Java
+
+The most common way to define custom workflow types is as workflow, using the primitives defined here,
+and delegating to custom containers where the logic is best done in a higher-level programming language.
+This avoids any language bias and the need to learn Brooklyn interfaces.
+However it is supported to provide custom workflow step types as Java classes in a bundle.
+
+To write a Java workflow step type, provide a class extending `WorkflowStepDefinition`,
+providing implementations for the following methods:
+
+```
+Object doTaskBody(WorkflowStepInstanceExecutionContext context);
+void populateFromShorthand(String value);
+boolean isDefaultIdempotent();
+```
+
+The first of these does the work of the step, resolving inputs and accessing context as needed via `context`.
+The second handles providing a cusotm shorthand, as described above;
+it can call to a superclass method `populateFromShorthandTemplate(TEMPLATE, value)`
+with the `TEMPLATE` for the class, if shorthand is to be supported.
+Finally, the third returns whether the step is idempotent, that is if the custom step is interrupted,
+can Brooklyn safely recover simply by rerunning it with the same inputs.
+As described [here](settings.md), it is recommended to write the step so that it is idempotent if possible.
+
+Once written, the class should be added to the Brooklyn Catalog,
+e.g. for a custom java step called `com.acme.YourJavaWorkflowStep` with shorthand name `your-step`,
+create a `catalog.bom` such as the following, and `br catalog add catalog.bom`:
+
+```
+brooklyn.catalog:
+ bundle: your-step-bundle
+ version: "1.0.0-SNAPSHOT"
+ items:
+ - id: your-step
+ format: java-type-name
+ itemType: bean
+ item:
+ type: com.acme.YourJavaWorkflowStep
+```
diff --git a/guide/blueprints/workflow/settings.md b/guide/blueprints/workflow/settings.md
index 421323b..6e0b5d9 100644
--- a/guide/blueprints/workflow/settings.md
+++ b/guide/blueprints/workflow/settings.md
@@ -165,8 +165,9 @@
as "sleep", "set-config", or "wait for sensor X to be true" are obviously idempotent; it also applies to `let` because
Brooklyn records a copy of the value of workflow variables on entry to each step and will restore them on a replay.
-However, for some step types, it is impossible for Brooklyn to infer whether they are idempotent: this applies to "
-external" steps such as `http` and `ssh`. It can also be the case that even where individual steps are idempotent, a
+However, for some step types, it is impossible for Brooklyn to infer whether they are idempotent: this applies to
+"external" steps such as `http` and `ssh`, and some `invoke-effector` steps.
+It can also be the case that even where individual steps are idempotent, a
sequence of steps is not. In either of these cases the workflow author should give instructions to Brooklyn about how
to "replay".
@@ -201,6 +202,11 @@
read-only step -- the step can be marked `idempotent: yes` and Brooklyn will support replay resuming at that step. (
However here, and often, this is unnecessary, if the nearest "replay point" is good enough.)
+The internal steps `workflow` and `invoke-effector` are by default considered idempotent
+if Brooklyn can tell they are running nested workflows at idempotent step.
+All other internal steps are idempotent.
+Actions such as `deploy-application` use special techniques internally to guarantee idempotency.
+
In some cases, it can be convenient to indicate default replayable/idempotency instructions when defining a workflow. As
part of any workflow definition, such as `workflow-effector` or a nested `type: workflow` step, the
entry `idempotent: all` indicates that all external steps in the workflow are idempotent; `replayable: automatically`
@@ -220,7 +226,9 @@
when defining a workflow
* **`replayable: from start`** to indicate that the start of the workflow is a valid replay point
* **`replayable: automatically`** to indicate that on an unhandled Brooklyn failover (DanglingWorkflowException), the workflow should attempt to "replay resuming", either from the last executed step if it is resumable, or from the last replay point
- * **`idempotent: all`** to indicate that external steps such as `http` and `container` in the workflow are resumable unless explicitly indicated otherwise (by default these are not; only internal steps known to be safely re-runnable are resumable)
+ * **`idempotent: all`** to indicate that all steps are idempotent and if interrupted there, the workflow can resume there,
+ unless explicitly indicated otherwise
+ (by default steps such as `http` and `container` are not; only internal steps known to be safely re-runnable are resumable)
Finally, it is worth elaborating the differences between the three types of retry behavior, as described on the `retry` step:
diff --git a/guide/blueprints/workflow/steps/index.md b/guide/blueprints/workflow/steps/index.md
index 458d1d7..073c265 100644
--- a/guide/blueprints/workflow/steps/index.md
+++ b/guide/blueprints/workflow/steps/index.md
@@ -9,6 +9,23 @@
- { section: Index of Step Types }
---
+Apache Brooklyn workflow supports a range of step types covering the most common activities
+commonly done as part of application management.
+These are divided into the following groups:
+
+* [Workflow Control](#workflow_control): use local variables and control flow,
+ with step types such as `let`, `return`, and `retry`
+* [External Actions](#external_actions): interact with external systems
+ using step types such as `container`, `ssh`, `winrm`, and `http`
+* [Application Models](#application_models): work with the models stored in Brooklyn,
+ doing things such as `invoke-effector`, `set-sensor`, `deploy-application`, and `add-entity`
+* [General Purpose](#general_purpose): miscellaneous step types such as `log` and `sleep`
+
+Custom step types can be written and added to the catalog, either written as workflow using these primitives
+(including doing virtually anything in a container) or by implementing a Java type, both [as described here](../nested-workflow.md).
+An index of all out-of-the-box step types is included at the [end of this section](#index_of_step_types).
+
+
{% jsonball steps from yaml file steps.yaml %}
{% assign step_summaries = "" | split: ", " %}
diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index ad327ad..1d29a95 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -365,6 +365,72 @@
optionally the `entity` where the sensor should be cleared (defaulting to the entity where the workflow is running)
output: the output from the previous step, or null if this is the first step
+ - name: deploy-application
+ summary: Deploys an application from a registered type or a blueprint
+ shorthand: '`deploy-application [TYPE]`'
+ input: |
+ * `type`: a registered type to deploy as a root application, without any configuration; exactly one of this and `blueprint` is required
+ * `blueprint`: the blueprint to deploy
+ * `format`: optional format specifier for the blueprint
+ output:
+ * `app`: the application instance deployed
+
+ - name: add-entity
+ summary: Deploys an application from a registered type or a blueprint
+ shorthand: '`add-entity [TYPE]`'
+ input: |
+ * `type`: a registered type to add as a child here, without any configuration; exactly one of this and `blueprint` is required
+ * `blueprint`: the blueprint of the entity, or a list of such blueprints, to be added at the current entity
+ * `format`: optional format specifier for the blueprint
+ output:
+ * `entities`: a list of entities added
+ * `entity`: if a single entity was added, that entity, otherwise unset
+
+ - name: delete-entity
+ summary: Deploys an application from a registered type or a blueprint
+ shorthand: '`delete-entity ENTITY`'
+ input: |
+ * `entity`: the entity or entity ID to delete (unmanage)
+ output: the output from the previous step, or null if this is the first step
+
+ - name: reparent-entity
+ summary: Moves an entity to be under a new parent
+ shorthand: '`reparent-entity child CHILD under PARENT`'
+ input: |
+ * `child`: the entity or entity ID to be moved
+ * `parent`: the entity or entity ID of the new parent
+ output: the output from the previous step, or null if this is the first step
+
+ - name: apply-initializer
+ summary: Moves an entity to be under a new parent
+ shorthand: '`apply-initializer [TYPE [at ENTITY]]`'
+ input: |
+ * `type`: a registered type to add as a child here, without any configuration; exactly one of this and `blueprint` is required
+ * `blueprint`: the blueprint of the entity, or a list of such blueprints, to be added at the current entity
+ * `entity`: the entity or entity ID where the initializer should be run, defaulting to the current entity
+ output: the output from the previous step, or null if this is the first step
+
+ - name: add-policy
+ summary: Adds a policy or other adjunct from a registered type or a blueprint
+ shorthand: '`add-policy [TYPE] [at ENTITY] [unique-tag UNIQUE_TAG]`'
+ input: |
+ * `type`: a registered type for a policy or other adjunct, to be attached to this entity, without any configuration; exactly one of this and `blueprint` is required
+ * `blueprint`: the blueprint for a policy, enricher, feed, or other adjunct, to be added at the current entity
+ * `entity`: the entity or entity ID where the adjunct should be added, defaulting to the current entity
+ * `unique-tag`: a tag to uniquely identify this adjunct, defaulting to the workflow step; this will replace any instance with the same unique-tag at the entity
+ (to make the operation idempotent)
+ output:
+ * `adjunct`: the policy or other adjunct added
+ * `policy` or `enricher` or `feed`: as above, depending on the type of the adjunct
+
+ - name: delete-policy
+ summary: Removes a policy or other adjunct at an entity
+ shorthand: '`delete-policy POLICY [at ENTITY]`'
+ input: |
+ * `policy`: the policy or adjunct to be removed, or the unique tag or ID of such an adjunct
+ * `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
+
-
section_name: General Purpose
diff --git a/guide/blueprints/workflow/variables.md b/guide/blueprints/workflow/variables.md
index 82d7e18..8065dae 100644
--- a/guide/blueprints/workflow/variables.md
+++ b/guide/blueprints/workflow/variables.md
@@ -144,8 +144,8 @@
The reason `let` is the only place operations is allowed is because Brooklyn is able to restore local variables
if a workflow is replayed from that step.
-This ensures that all the internal steps (excluding steps that act externally such as `ssh` or `container`)
-are individually idempotent, so if interrupted at the step can be safely resumed from that step.
+This ensures that most steps are individually idempotent,
+so if interrupted at the step can be safely resumed from that step.
For example, if the following were allowed:
@@ -166,6 +166,8 @@
Where workflows need to be resumed on interruption or might replay steps to recover from other errors,
idempotency is an important part of reliable workflow design.
+External actions such as `http` and `container` are not guaranteed to be idempotent,
+and neither are some `invoke-effector` calls, so care must be taken here for workflows to be replayable.
Good practice and the settings available for resilient workflows are covered in [Workflow Settings](settings.md).
