From b46f07299c0f54749c2e84eca94cf1d3ae28d635 Mon Sep 17 00:00:00 2001 From: Christian J Date: Tue, 22 Sep 2026 15:20:40 -0500 Subject: [PATCH 1/2] Document that Liquid filters are not allowed inside {% if %} conditions Customers hit this when writing grain `when` conditions such as `{% if .inputs.network_type | strip | downcase == "vlan" %}`. Liquid only allows filters in output tags and in `assign`, so the expression fails to evaluate and the grain is not gated as intended. - Add a "Using Liquid filters in a condition" subsection under `when`, showing the invalid pattern and the `assign` workaround, plus an `allowed-values` alternative - Note the same rule in the templating engine section - Add the `assign` pattern to the input `visible` examples Co-Authored-By: Claude Opus 5 (1M context) --- .../blueprints/blueprints-yaml-structure.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/blueprint-designer-guide/blueprints/blueprints-yaml-structure.md b/docs/blueprint-designer-guide/blueprints/blueprints-yaml-structure.md index 48944beb5..f5e3a7427 100644 --- a/docs/blueprint-designer-guide/blueprints/blueprints-yaml-structure.md +++ b/docs/blueprint-designer-guide/blueprints/blueprints-yaml-structure.md @@ -608,6 +608,52 @@ grains: spec: ... ``` +#### Using Liquid filters in a condition + +Liquid filters, such as [strip](https://shopify.github.io/liquid/filters/strip/) and [downcase](https://shopify.github.io/liquid/filters/downcase/), can only be used inside output tags (`{{ ... }}`) and in `assign` tags. They are **not** supported inside the condition of an `{% if %}` tag, so the following is invalid: + +```yaml +grains: + create_underlay: + kind: ansible + # Invalid - filters cannot be used inside an {% if %} condition + when: '{% if .inputs.network_type | strip | downcase == "vlan" %}true{% else %}false{% endif %}' + spec: ... +``` + +The expression fails to evaluate, so the grain is not skipped or run as intended. + +Instead, apply the filters in an `assign` tag and compare the assigned variable in the `{% if %}`: + +```yaml +grains: + create_underlay: + kind: ansible + when: '{% assign network = .inputs.network_type | strip | downcase %}{% if network == "vlan" %}true{% else %}false{% endif %}' + spec: ... +``` + +An `assign` tag produces no output of its own, so the `when` value still renders as exactly `true` or `false`. + +:::tip +You can avoid the need for filters altogether by normalizing the value at the input level with `allowed-values`, and then comparing the input directly: + +```yaml +inputs: + network_type: + type: string + allowed-values: ["vlan", "vpc"] + +grains: + create_underlay: + kind: ansible + when: '{% if .inputs.network_type == "vlan" %}true{% else %}false{% endif %}' + spec: ... +``` + +Note that a direct comparison is case-sensitive and does not tolerate leading or trailing spaces, which is why the `assign` pattern above is needed when the value can come from a free-text input or a grain output. +::: + ### `approvals` Use `approvals` on a grain when you need a human gate before that grain executes. @@ -1176,6 +1222,10 @@ In the below example the [downcase](https://shopify.github.io/liquid/filters/dow - bucket_name: '{{ .inputs.bucket_name | strip }}-bucket-{{ envId | downcase }}' ``` +:::note +Filters are only valid inside output tags (`{{ ... }}`) and in `assign` tags. They cannot be used inside the condition of an `{% if %}` tag - see [Using Liquid filters in a condition](#using-liquid-filters-in-a-condition). +::: + For details and examples of how to use the parameters from the parameter store inside blueprints, check [this article](#parameters). ### Dynamic Attributes @@ -1700,6 +1750,9 @@ The `visible` property uses Liquid templating syntax to create dynamic condition - `{% if inputs.field_name == "value" %}true{% else %}false{% endif %}` - Show input when another field equals a specific value - `{% if inputs.field_name != "value" %}true{% else %}false{% endif %}` - Show input when another field doesn't equal a specific value +Liquid filters cannot be used inside the condition of an `{% if %}` tag. To filter a value before comparing it, assign it first and compare the assigned variable: +- `{% assign field = inputs.field_name | strip | downcase %}{% if field == "value" %}true{% else %}false{% endif %}` - Show input when another field equals a specific value, ignoring case and surrounding spaces + **Useful Liquid Templating Resources:** - [Liquid Templating Introduction](https://shopify.github.io/liquid/basics/introduction/) - Learn the basics and syntax of Liquid templating - [Liquid Playground](https://liquidjs.com/playground.html) - Interactive playground to test and experiment with Liquid expressions From 010fab28a2657785a1797ee9c3a3603127e9d075 Mon Sep 17 00:00:00 2001 From: Christian J Date: Tue, 22 Sep 2026 15:25:17 -0500 Subject: [PATCH 2/2] Ignore local spellcheck reference file --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index b2d6de306..881987919 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# spellchecker reference file +dictionary.dic + # Dependencies /node_modules