> For the complete documentation index, see [llms.txt](https://docs.wem.io/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wem.io/platform/wemmodeler/data-model/settings-folder.md).

# Settings Folder

All your application settings in one place, manageable from the devops dashboard.

### Introduction

The Settings folder is used for configuration values that you want to manage per Runtime environment rather than directly in the project. An administrator then decides in the DevOps portal what each environment puts into it.

The clearest way to think about the folder is as your application's configuration file. Anything a developer would traditionally keep out of the source code and in an application settings file is a good candidate here — though not every setting, and not every project, needs to use it.

Its primary purpose is **services**. When your application consumes an external service, everything that service needs in order to be reached belongs in the Settings folder: the endpoint URL, the account or tenant identifier, and the key or secret used to authenticate. Alongside that, the folder is a natural home for values that simply differ per environment, such as feature toggles, thresholds and cut-over dates.

{% hint style="info" %}
A setting can be changed on Staging or Live without republishing the project. But only when the project is published after the fields are created, the configuration changes made in the modeler are set when the project is published. 
{% endhint %}

### How it works

The Settings folder is a single, fixed folder in the Data Model with the technical name `Settings`. A project has at most one of them (see [Creating the Settings](#creating-the-settings-folder) folder when it is missing in your project).

Inside the folder you can create **sub folders** to group related settings, and the **fields** themselves that holds the actual setting/value. This can be used to group settings per service for example; a sub folder per integration, holding that integration's URL, identifier and key together.

An important destinction between calculated field and the settings field is when their value is updated. When a calculated fields value is changed it is only updated on a specific runtime when the project is published to that runtime. The Settings folder values always use the current value set in the runtime, this means it can be changed/updated without the need to publish the project. Constants and fields that dont need to be managed and updated on portal level can stay as calculated field to limit the extra devop management overhead. 

Every setting field is one of five primitive types:

* Boolean
* Number
* Text
* Date Time
* Duration

{% hint style="info" %}
You cannot create lists inside the setting folder.
{% endhint %}

Each setting consist of the following information:

* Name
* Technical name
* Type
* Description
* Required 
* Secret
* Default

#### Required settings

Marking a setting as required declares that the application cannot run correctly without a value for it. This is checked in two places:

* **During publishing**, the publish process reports required settings that have no value configured on the target environment, so that the gap surfaces before users hit it.
* **At runtime**, the default value is used when a setting has not been configured on the environment and an application log warning is created referencing the field.

#### Preview

Settings cannot be configured on **Preview**. There is no place to set a value for it, so Preview always the default value for every setting.

This has a direct consequence for how you model default values: **the default should be the value that is correct and safe for a developer working in Preview.** Treat the default as the development configuration, and treat the values set on Staging and Live as the deviations from it.

{% hint style="danger" %}
 A service that requires a secret should not be reached from Preview, since Preview cannot be given an environment value and a secret must not be stored in a default value expression. Design your flow so this is a handled case rather than an unexplained failure.
{% endhint %}

#### How a value is resolved

When your application reads a setting field, the Runtime resolves the value in this order:

1. **The value defined on the Runtime environment**, if one has been set.
2. **The default value defined in the Modeler**, if no environment value exists.

Clearing an environment value therefore does not empty the setting, it returns the setting to its modelled default.

#### Secret settings

A setting field can be marked as **secret**. A secret setting is stored encrypted on the Runtime environment, and its value is redacted wherever settings are listed back in the devops portal, so it can be written but not read out from devops. However the modeler using can use this field meaning that they can create a screen exposing the secret. 

{% hint style="danger" %}
Do not put a secret in the default value expression. The default value expression is part of the project and is stored **unencrypted**, and it is visible to every Modeler user with access to the project. Declare the field as secret in the Modeler, leave its default value empty, and have the value set on Staging and Live. 
{% endhint %}

{% hint style="danger" %}
Marking a setting as secret hides its value from other Modeler users and from anyone viewing the DevOps portal — it does not, and cannot, hide the value from someone building the project itself. If a field can be used anywhere in the application, a Modeler user can construct a flow that exposes its value (for example by writing it out to a visible field). Secret is not a way to keep keys and secrets from the Modelers who build with them; it protects the value from casual exposure and from other users.
{% endhint %}

### Creating the Settings folder

The Settings folder is created automatically for new projects.

For projects created before the Settings folder was introduced, it is not present by default and needs to be added through [Legacy Settings](/platform/wemmodeler/project-settings.md). If the project already has a folder named in settings the modeler will give you an error, this can be resolved by renaming the existing settings folder. 

{% hint style="warning" %}
Once the Settings folder has been created it cannot be removed again. You can, of course, choose to leave the folder empty, or leave individual sub folders unused. 
{% endhint %}

### Adding a setting field

Right-click the Settings folder (or one of its sub folders) and choose to add a new field. Because setting fields are always fields of a primitive type, the available options are narrower than in the rest of the Data Model.

You can create sub folders inside the Settings folder to group related settings, for example one sub folder per service. Sub folders exist only in the Modeler; DevOps has no concept of a folder, so a setting inside a sub folder is only visible there through its technical name, which includes the folder as a dot-separated prefix, for example `CrmIntegration.ApiKey`.

<table><thead><tr><th width="179">Property</th><th width="143.3333740234375">Type</th><th width="83.6666259765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Name</code></td><td>Text</td><td>Yes</td><td>The name of the setting as shown in the Modeler.</td></tr><tr><td><code>Technical name</code></td><td>Text</td><td>Yes</td><td>The name WEM uses to reference the setting in expressions. Generated from the name, and also the name under which the setting is identified on the Runtime environment.</td></tr><tr><td><code>Description</code></td><td>Text</td><td>No</td><td>A description of the setting. Unlike descriptions elsewhere in the Data Model, this one is not only informational within the Modeler: it is shown to the administrator who configures the value in the DevOps portal. Use it to state what is expected in the setting and where the value comes from. Available on setting fields only, not on (sub) folders.</td></tr><tr><td><code>Type</code></td><td>Boolean / Number / Text / Date Time / Duration</td><td>Yes</td><td>The data type of the setting. Can only be chosen when the field is created.</td></tr><tr><td><code>Required</code></td><td>Toggle</td><td>N/a</td><td>Declares that the application needs a value for this setting. Reported during publishing when unset.</td></tr><tr><td><code>Secret</code></td><td>Toggle</td><td>N/a</td><td>Stores the value encrypted on the Runtime environment and redacts it when settings are inspected in DevOps. Values for secret settings should only be entered on the Runtime environment.</td></tr><tr><td><code>Default value</code></td><td>Expression</td><td>No</td><td>The expression evaluated when the Runtime environment has no value of its own. Always used on Preview. Leave empty for secrets.</td></tr></tbody></table>

### Configuring values in DevOps

Values are set per environment, on the DevOps portal for that environment. This applies to **Staging** and **Live**; Preview cannot be configured as there is no access to the preview devops portal.

Navigate to the **Application** tab, then **Application settings** in the overflow menu. This opens an overlay that lists, at the bottom, the settings configured for that project.&#x20;

From the context menu on a setting you can:

* **Change value** — set or update the value for this environment.
* **Clear value** — remove the value, so the setting falls back to its default value.
* **View details** — open the detail screen for the setting.

The **View details** screen shows:

<table><thead><tr><th width="204.6666259765625">Property</th><th>Description</th></tr></thead><tbody><tr><td>Technical field name</td><td>The technical name of the setting.</td></tr><tr><td>Data model field ID</td><td>The identifier of the underlying field in the Data Model.</td></tr><tr><td>Field type</td><td>The data type of the setting.</td></tr><tr><td>Has default value</td><td>Whether a default value is defined in the Modeler.</td></tr><tr><td>Required</td><td>Whether the setting is marked as required.</td></tr><tr><td>Configured value</td><td>The value set on this environment, if any. Redacted for secrets.</td></tr><tr><td>Application ID</td><td>The identifier of the application.</td></tr><tr><td>Date created</td><td>When the setting was first configured on this environment.</td></tr><tr><td>Date modified</td><td>When the setting was last changed on this environment.</td></tr></tbody></table>

Because the values live on the environment and not in the project, they survive a republish and the settings itself is part of the project definition and gets copied along, the value is only on the runtime and does not get copied.&#x20;

{% hint style="info" %}
&#x20;The list of settings on an environment is refreshed by publishing. A newly modelled setting, a renamed technical name, or a change to the description, required flag or secret flag becomes visible on the environment after the project has been published to it.
{% endhint %}

### Using settings in your application

A setting field is read exactly like any other field in the Data Model: It can be used in an expression, in a node property, or in a template. There is no dedicated function to read a setting.

For example, a setting field `ApiBaseUrl` in the Settings folder shows up in an expression as:

```
[Settings.ApiBaseUrl]
```

{% hint style="info" %}
Settings are read-only from within the application. There is no way to assign to a setting from a flowchart, which is deliberate: a setting describes how the environment is configured, not application state. If you need a value the application can change, use an ordinary field.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.wem.io/platform/wemmodeler/data-model/settings-folder.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.