Add apply for to the language reference documentation

fixes #10409

diff --git a/doc/20-language-reference.md b/doc/20-language-reference.md
index f8aa50e9c0f4f3753bc83f4cbec5d12ce8cbbff9..557c751dbe1d58196770c0905dd73a042b967c99 100644 (file)
--- a/doc/20-language-reference.md
+++ b/doc/20-language-reference.md
@@ -411,6 +411,42 @@ Any valid config attribute can be accessed using the `host` and `service`
 variables. For example, `host.address` would return the value of the host's
 "address" attribute - or null if that attribute isn't set.
 
+More usage examples are documented in the [monitoring basics](3-monitoring-basics.md#using-apply-expressions)
+chapter.
+
+## <a id="apply-for"></a> Apply For
+
+[Apply](20-language-reference.md#apply) rules can be extended with the
+[for loop](20-language-reference.md#for-loops) keyword.
+
+    apply Service "prefix-" for (key => value in host.vars.dictionary) to Host {
+      import "generic-service"
+
+      check_command = "ping4"
+      vars.host_value = value
+    }
+
+
+Any valid config attribute can be accessed using the `host` and `service`
+variables. The attribute must be of the Array or Dictionary type. In this example
+`host.vars.dictionary` is of the Dictionary type which needs a key-value-pair
+as iterator.
+
+In this example all generated service object names consist of `prefix-` and
+the value of the `key` iterator. The prefix string can be omitted if not required.
+
+The `key` and `value` variables can be used for object attribute assignment, e.g. for
+setting the `check_command` attribute or custom attributes as command parameters.
+
+`apply for` rules are first evaluated against all objects matching the `for loop` list
+and afterwards the `assign where` and `ignore where` conditions are evaluated.
+
+It is not necessary to check attributes referenced in the `for loop` expression
+for their existance using an additional `assign where` condition.
+
+More usage examples are documented in the [monitoring basics](3-monitoring-basics.md#using-apply-for)
+chapter.
+
 ## <a id="group-assign"></a> Group Assign
 
 Group objects can be assigned to specific member objects using the `assign where`

diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md
index 371aff7fcc950f7059699209ccb1212c2106efc1..ec53ed140071f3a70e79c37962d3c78ce3a76231 100644 (file)
--- a/doc/3-monitoring-basics.md
+++ b/doc/3-monitoring-basics.md
@@ -615,8 +615,8 @@ Detailed examples can be found in the [recurring downtimes](5-advanced-topics.md
 ### <a id="using-apply-for"></a> Using Apply For Rules
 
 Next to the standard way of using [apply rules](3-monitoring-basics.md#using-apply)
-there is the requirement of generating apply rules objects based on set (array or
-dictionary).
+there is the requirement of applying objects based on a set (array or
+dictionary) using [apply for](20-language-reference.md#apply-for) expressions.
 
 The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
 and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.