---
title: Configure Optimizely Forms
slug: cms-12/docs/configuring-optimizely-forms
docTags: 
createdAt: 2026-08-10T15:56:03.000Z
---

:::hint{type="info"}
**Note**
[Optimizely Forms](docId:3SbSlJZIS_3iFmghfQA3J) is only supported by MVC-based websites and HTML5-compliant browsers.
:::

Optimizely Forms stores its fundamental configuration in the  `_protected/EPiServer.Forms/Forms.config` file.

:::hint{type="warning"}
**Breaking change**
`Forms.config` was migrated to `appsettings.json`. From version 5.4 onward, Optimizely Forms uses `appsettings.json` file to store its fundamental configuration. You can upgrade and use your former `Forms.config` but Optimizely will stop supporting the file in the next major version.

To use the new configuration for Forms, add a Forms section your `appsettings.json` like the following example.

```json
{
  "EPiServer": {
    "Forms": {
      "FormsConfig": {
        "VisitorSubmitTimeout": 1,
        "DisableFormCookies": false,
        "DataExportBlobProviderName": "DefaultDataExportBlobProvider",
        "SerializingObjectUsingNameValueFormat": true,
        "SendMessageInHTMLFormat": true,
        "MinimumAccessRightLevelToReadFormData": "Edit",
        "CoreController": "/EPiServer.Forms/DataSubmit",
        "DefaultUploadExtensionBlackList": "asp,aspx,asa,ashx,asmx,bat,chm,class,cmd,com,config,dll,exe,hta,htr,htw,jse,json,lnk,mda,mdb,msc,msh,pif,printer,ps1,ps2,reg,rem,scf,scr,sct,shtm,shtml,soap,stm,svc,url,vb,vbe,vbs,vsix,ws,wsc,wsf,wsh,xamlx,htm,html,js,jar",
        "FormElementViewsFolder": "~/Views/Shared/ElementBlocks",
        "WorkInNonJSMode": false,
        "InjectFormOwnStylesheet": true,
        "InjectFormOwnJQuery": true,
        "RenderingFormUsingDivElement": false,
        "PreconfiguredFeeds": [
          {
            "Id": "Your Id",
            "Description": "Your Description",
            "Url": "Your Url",
            "KeyXPath": "Your KeyXPath",
            "ValueXPath": "Your ValueXPath",
            "CacheTimeout": 90
          }
        ]
      },
      "FormsPermanentStorageProvider": {
        "DefaultProvider": "DdsPermanentStorage",
        "Providers": {
          "DdsPermanentStorage": {
            "Type": "EPiServer.Forms.Core.Data.DdsPermanentStorage, EPiServer.Forms.Core",
            "Parametters": {}
          },
          "DdsEncryptedPermanentStorage": {
            "Type": "EPiServer.Forms.Core.Data.Internal.DdsEncryptedPermanentStorage, EPiServer.Forms.Core",
            "Parameters": {
              "CryptoEngineType": "EPiServer.Forms.Crypto.AzureKeyVault.Internal.AzureKeyVaultCryptoEngine, EPiServer.Forms.Crypto.AzureKeyVault",
              "KeyIdentifier": "Your KeyIdentifier",
              "TenantId": "Your TenantId",
              "ClientId": "Your ClientId",
              "ClientSecret": "Your ClientSecret"
            }
          }
        }
      }
    }
  }
}
```

As an alternative method, you can also config your Optimizely Forms from `Startup.cs` file in `ConfigureServices` function with following syntax:

```csharp
services.Configure<FormsConfigOptions>(options => options.CoreController = "Your Controller");
services.Configure<FormsPermanentStorageProviderOptions>(options => options.DefaultProvider = "Your DefaultProvider");
```

You need to add the lines above after your `services.AddCmsHost()` for it to take effect if you still have your `Forms.config` in your project. The final value will be the value in `appsettings.json` however.
:::

## Restrict access to data

The following configuration restricts who can view submitted form data. **Edit** is the default; an editor should at least have Edit access rights on the form content to view `SubmissionData`.

```csharp
minimumAccessRightLevelToReadFormData="Edit"
```

Suitable values for `minimumAccessRightLevelToReadFormData` are as follows:

```csharp
NoAccess = 0, Read = 1, Create = 2, Edit = 4, Delete = 8, Publish = 16, Administer = 32, FullAccess = 63
```

For example, if you change the access rights to Publish, only a user who has `Publish`, `Administer` and `FullAccess` access rights on that form can see the `SubmissionData`.

## Send emails

:::hint{type="info"}
**Note**
To send email after a site visitor submits a form, you must modify the *appSettings.json* settings for your website as described in [Configure your email server](docId:3xHKpZbHS-aJgOSfh6KiB).
:::

Send email in HTML format, otherwise, it uses plain text.

```csharp
sendMessageInHTMLFormat="true"
```

## File uploads

By default, the `FileUploadElement` does not let a visitor upload the following types of file extensions.

```csharp
defaultUploadExtensionBlackList = "asp,aspx,asa,ashx,asmx,
bat,
chm, class, cmd, com, config,
dll,
exe,
hta, htm, html, htr, htw,
jar, js, jse, json,
lnk,
mda, mdb, msc, msh,
pif, printer, ps1, ps2,
reg, rem,
scf, scr, sct, shtm, shtml, soap, stm, svc,
url,
vb, vbe, vbs, vsix,
ws, wsc, wsf, wsh,
xamlx"
```

## Use controllers

Optimizely Forms is block-based and stays in a page. Without JavaScript, Forms post data from a visitor to its page. With JavaScript, Forms post data from a visitor to its `CoreController`. `EPiServer.Forms.Controllers.DataSubmitController` is the default `CoreController`, which is a normal ASP.NET MVC controller. If you want to use your own controller, you must map the route in `Global.asax` to your controller, and tell Forms to submit data to your controller by changing the following configuration.

```csharp
coreController="/EPiServer.Forms/DataSubmit"
```

## Default location for view templates

Specify the default location to search for `ElementBlocks`' view templates. A developer also can override this behavior by implementing `ICustomViewLocation` or inheriting from `CustomViewLocationBase`.

```csharp
formElementViewsFolder="~/Views/Shared/ElementBlocks"
```

## Forms and JavaScript environments

Optimizely Forms detects the JavaScript capability of the browser to determine its behavior.

- Using an HTML5 JavaScript-enabled browser, visitors have a better and richer user interface experience.
- Working with non-JavaScript browsers, Optimizely Forms has to use server-side redirection and disable some features such as interaction and validation.

In some situations, you can force Forms to work in a non-JavaScript environment by setting this configuration to **true**.

```csharp
workInNonJSMode="false"
```

## Forms and jQuery

Optimizely Forms requires jQuery 1.7.2+ to provide a better experience in view mode (interaction, steps navigation, validation, save/load data to localStorage, etc). If your website already has jQuery 1.7.2+, you can save some payload and network transmission for your visitors by telling Optimizely Forms not to inject its jQuery instance. Forms uses the site’s jQuery instance without a problem.

```csharp
injectFormOwnJQuery="true"
```

## Disable the default stylesheet

Optimizely Forms has a default stylesheet (`EPiServerForms.less`), using BEM methodology to name CSS classes and decorate HTML element tags; it is a fundamental, minimal `.less` file, and easy to modify. However, if you prefer not to use this default stylesheet, you can disable it by changing `injectFormOwnStylesheet` to false.

```csharp
injectFormOwnStylesheet="false"
```

## Configure the submit cookie timeout

Configure for days that Forms keeps the state of relation *(in visitor's cookie)*  between Visitor-Forms-Submission. This affects the progressive submission cookie, and the visitor identification cookie.

```csharp
visitorSubmitTimeout="90"
```

## Render forms as a \<div> tag

A form is rendered as a `<form>` tag in view mode by default. From version 3.1, if you want to render the form as a `<div>` tag, set this configuration to `true`.

```csharp
renderingFormUsingDivElement="true"
```

## Use Webhook receivers

From version 4.3, you can set up the kind of data format used before sending data to a webhook receiver by using:

```csharp
serializingObjectUsingNameValueFormat="true"
```

The default value of this key is `true`, meaning you should use that JSON object data type to communicate with webhook receivers. The key-value dictionary data format is used if you use the value `false`.

## Disable form cookies for GDPR

`DisableFormCookies` was introduced into Forms configuration to provide better GDPR compliance for your sites. Enable this option to prevent cookies from being added to site users.

:::hint{type="info"}
**Note**
Allow anonymous submissions are required for Forms submitted when `DisableFormCookies` is enabled because a user without cookies is not identified and is treated as anonymous.
:::

```csharp
DisableFormCookies="false"
```

## Hide Partial Submissions from Admin or Edit View (GDPR Compliance)

`HidePartialSubmissions` was introduced into Forms configuration in version 5.5.0 to provide better GDPR compliance for your sites. Enable this option to hide partial submission data from external UI views such as form submission history and exported data and disable partial execution from actors. Also, enable this option to set the retention policy of partial data to a minimum period of one day.

:::hint{type="info"}
**Note**
Enabling this option will disable all actors partial execution in multi-step forms except base `SaveDataToStorageActor` to ensure basic functionality
:::

```csharp
HidePartialSubmissions="false"
```

## Related blog posts

- [How to render forms in a dialog](https://world.optimizely.com/blogs/dac-thach-nguyen/dates/2018/12/episerver-forms-how-to-render-forms-in-a-dialog/)
- [Create custom Episerver Forms container](https://swapcode.wordpress.com/2019/03/24/create-custom-episerver-forms-container/)