> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/pipes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/pipes/valves.md).

# Valves

A VALVE is a highly specialised building block. In general, it operates on data exposed by the PIPE where the VALVE “lives”. By chaining multiple VALVES one can achieve customised authentication/authorization making the system follow current business requirements but also cater for future requirements changes.

## Common configuration

These configuration properties applies to all valves:

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>name</code></td><td>Valve name (alias or fully qualified class name).</td><td></td><td>true</td></tr><tr><td><code>enabled</code></td><td>Flag to control if valve is enabled (i.e. included in pipe) or not. Use this property to <em>temporary</em> disable a valve.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>exec_if_expr</code></td><td>Predicate expression controlling if valve should be executed or not in the current context. For details, see <a href="#execution-control">execution control</a>.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>config</code></td><td>Valve specific configuration object. This object is passed to the valve during initialisation and is the configuration the valve has access to.</td><td><code>{}</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "name":"<alias>",
    "enabled": true,
    "exec_if_expr": "request.exec === 'true'",
    "config": {

    }
}
```

{% endtab %}
{% endtabs %}

## Execution control

You can control valve execution in runtime using the *exec-if*  predicate expression (a boolean expression that returns `true` or `false`). If expression evaluated to `true`, the valve is executed (this is the default behaviour).

The actual filter is an ECMA-script (JavaScript) that MUST evaluate to `true`, `false` or to a `boolean function` returning `true` or `false`.

```
// Disable valve 
"exec_if_expr": "false"

// Only execute if session contains a username property
"exec_if_expr": "session.username != null"
```

During expression evaluation data is made available in *scopes*. A scope is a map (i.e key-values or hash) where values are accessed using a name and plain dot notation.

{% hint style="info" %}
In JavaScript dot notation is NOT supported for list/array indexing.

Use the following syntax to address an element in a list:

`state.items[0].id`

It is also possible to use property expansion in expressions to expand the value before the script is evaluated:

`${state.items.0.id}`
{% endhint %}

<pre><code><strong>// Get value of request parameter "username"
</strong><strong>request.username
</strong><strong>
</strong><strong>// Get id of current session
</strong><strong>session.id
</strong><strong>
</strong><strong>// Get first value of multivalue "roles" stored in session
</strong><strong>session.roles[0]
</strong><strong>
</strong><strong>// Get value "otp" from state set by previous valve
</strong><strong>state.otp
</strong></code></pre>

The following are scopes available:

<table><thead><tr><th>Name</th><th>Description</th><th data-type="checkbox">Case-insensitive</th></tr></thead><tbody><tr><td><code>request</code></td><td>The current pipe request</td><td>true</td></tr><tr><td><code>session</code></td><td>The current session</td><td>false</td></tr><tr><td><code>state</code></td><td>The current state</td><td>false</td></tr><tr><td><code>items</code></td><td>The current items</td><td>false</td></tr><tr><td><code>exports</code></td><td>Authenticator globals. Only available if pipe is called in an authentication context (i.e. by an authenticator).</td><td>false</td></tr></tbody></table>