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.

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.

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 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

You cannot create lists inside the setting folder.

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.

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.

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.

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.

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.

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. 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.

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.

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.

Property	Type	Required	Description
Name	Text	Yes	The name of the setting as shown in the Modeler.
Technical name	Text	Yes	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.
Description	Text	No	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.
Type	Boolean / Number / Text / Date Time / Duration	Yes	The data type of the setting. Can only be chosen when the field is created.
Required	Toggle	N/a	Declares that the application needs a value for this setting. Reported during publishing when unset.
Secret	Toggle	N/a	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.
Default value	Expression	No	The expression evaluated when the Runtime environment has no value of its own. Always used on Preview. Leave empty for secrets.

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.

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:

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

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.

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.

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]

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.