Umbraco Forms is a tool that lets you build forms of all shapes and sizes and put them on your Umbraco websites. Build forms using a long list of elements like multiple choice, dropdowns, text areas and checkboxes. Choose between a series of different workflow and control what happens once a form has been submitted.

Purchase Umbraco Forms or sign up for an Umbraco Cloud project where Umbraco Forms is part of the package.

Quick Links

This article shows how to manually upgrade Umbraco Forms to run the latest version.

When upgrading Umbraco Forms, be sure to also consult the version specific upgrade notes to learn about potential breaking changes and common pitfalls.

Get the latest version of Umbraco Forms

To get the latest version of Umbraco Forms, you can upgrade using:

• NuGet

• Visual Studio

NuGet

• NuGet installs the latest version of the package when you use the dotnet add package Umbraco.Forms command unless you specify a package version: dotnet add package Umbraco.Forms --version <VERSION>

• After you have added a package reference to your project by executing the dotnet add package Umbraco.Forms command in the directory that contains your project file, run dotnet restore to install the package.

Visual Studio

1. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... in Visual Studio, to upgrade your Forms:

2. Select Umbraco.Forms.

3. Select the latest version from the Version drop-down and click Install.

1. When the command completes, open the .csproj file to make sure the package reference is updated:

   Copy

   <ItemGroup>
     <PackageReference Include="Umbraco.Forms" Version="xx.x.x" />
   </ItemGroup>

Umbraco contains the Forms section, by default. You will see a similar interface, when you click on the Forms section in the Umbraco Backoffice.

Video Tutorial

To install the Umbraco Forms package (Umbraco.Forms), follow these steps:

1. Identify the Umbraco CMS version your project is running.

2. Find a compatible version of Umbraco Forms that matches your Umbraco CMS version. A list of Umbraco Forms versions can be found on .

3. Run the following command on a command prompt of your choice, replacing <version_number> with the appropriate version identified above:

4. Restart the web application using the following command:

Start Building Forms

Once the installation is successful, you will see a similar screen in the Forms section:

Using Forms

For details on using Forms, see the .

The date picker uses a front-end library called to display a UI to pick dates.

Pikaday date picker can be localised based on the page the Form is rendered on.

The date picker displays the picked date in the required locale. Using JavaScript, a hidden field is updated with a standard date format to send to the server for storing record submissions. This avoids the locale mixing up the dates.

To achieve localized date, a Razor partial view is included at /Views/Partials/Forms/Themes/default/DatePicker.cshtml.

The DatePicker.cshtml includes the moment-with-locales.min.js library to help with the date locale formatting and the appropriate changes to Pikaday to support the locales. If you wish to use a different DatePicker component, edit the DatePicker.cshtml file as per your needs.

Configure the Year range

The Date picker has a configuration setting to control the number of years shown in the picker. The default value is 10 years.

You can configure the settings in the appSettings.json file:

Update DatePickerYearRange to a higher number (for example: 100) to increase the numbers of years available in the Date picker.

In Umbraco Forms, reCAPTCHA V3 comes out of the box.

reCAPTCHA v3 allows you to verify if an interaction is legitimate without any user interaction.

Enabling reCAPTCHA V3

Follow these steps to enable reCAPTCHA V3 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v3 enabled.

3. Add a new question and select ReCAPTCHA v3 with Score as its answer type.

4. Make sure the field is set as Mandatory.

5. Configure ReCAPTCHA settings in the appSettings.json file to include public and private keys:

You can create your keys by logging into your .

Umbraco Forms comes with some built-in fields however it is possible to exclude/remove them if necessary. There might some use cases where you have no use for file upload and don't want editors using them. Or perhaps you want to remove a field to replace it with one with enhanced functionality that you build yourself.

Example

The following class shows how to exclude built-in field types using a custom composer. The Password, Recaptcha2 and RichText field types (or "answers") will no longer be available for selection when creating a form in the backoffice.

A unique migration ID is generated for each Umbraco Forms upgrade that requires a migration. The migration IDs are all listed in this article.

For Umbraco Forms to work correctly, you need to include some client dependencies.

Client-Side Validation

Umbraco Forms ships with client-side form validation features provided by the ASP.NET Client Validation library.

You can use the following Razor helper to output script tags containing the dependencies. To access this method you will need a reference to Umbraco.Forms.Web:

@using Umbraco.Forms.Web
<head>
    @Html.RenderUmbracoFormDependencies()
</head>

Alternatively, you can add the dependencies to the body tag:

@using Umbraco.Forms.Web
...

<body>
    @Html.RenderUmbracoFormDependencies()
</body>

All dependencies originate from your Umbraco Forms installation, which means that no external references are needed.

Validation Using jQuery

If you want to use jQuery as your validation framework for Umbraco Forms, you can manually add the following client dependencies:

• jQuery (JavaScript library)

• jQuery validate (jQuery plugin that provides client-side Form validation)

• jQuery validate unobtrusive (Add-on to jQuery Validation that provides unobtrusive validation via data-* attributes)

You should remove any calls to @Html.RenderUmbracoFormDependencies(Url).

The easiest way to add the dependencies is to fetch them from a CDN. There are various CDN services you can use:

• For example: Microsoft CDN.

• Other CDN services you might want to look at are https://www.jsdelivr.com/ and https://cdnjs.com/about, which may offer better performance and more reliable service.

To add the three client dependencies, see the examples below:

Example within head tags.

<head>
    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.0.0.min.js"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.16.0/jquery.validate.min.js"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/mvc/5.2.3/jquery.validate.unobtrusive.min.js"></script>
</head>

Example within body tags.

When adding the script to the bottom of the page, you will also need to render the scripts. For more information, see Rendering Forms Scripts article.

<body>
    <!-- Page content here -->

    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.0.0.min.js"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.16.0/jquery.validate.min.js"></script>
    <script src="https://ajax.aspnetcdn.com/ajax/mvc/5.2.3/jquery.validate.unobtrusive.min.js"></script>
</body>

There are three options available for rendering a form.

Rendering Using a View Component

To display a form in your view, you can make a call to a view component:

@await Component.InvokeAsync("RenderForm", new { formId = Guid.Parse("<form guid>"), theme = "default", includeScripts = false })

Four parameters can be provided:

• formId is the GUID of a form.

• theme is the name of a theme. If not provided, the default theme is used (see Themes).

• includeScripts indicates whether scripts should be rendered with the form (see Rendering Scripts.

• recordId is an optional existing record GUID, used if editing records via the website is enabled in configuration

Usually, rather than hard-coding the form's GUID, you'll use a form and/or theme picker property on your page:

@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false })

Rendering Using a Tag Helper

If you prefer a tag helper syntax, you can use one that ships with Umbraco Forms.

Firstly, in your _ViewImports.cshtml file, add a reference to the Umbraco Forms tag helpers with:

@addTagHelper *, Umbraco.Forms.Web

Then in your view you can use:

@if (Model.Form.HasValue)
{
    <umb-forms-render form-id="@Model.FormId.Value" theme="@Model.FormTheme" exclude-scripts="true" />
}

Rendering Using a Macro

With a grid or Rich Text Editor, you need to use a macro. This is also available as an option to display a form in your view, where you provide three parameters:

@await Umbraco.RenderMacroAsync("renderUmbracoForm", new { FormGuid = "<form guid>", FormTheme = "default", ExcludeScripts = "1" })

• FormGuid is the GUID of a form.

• FormTheme is the name of a theme. If not provided, the default theme is used.

• ExcludeScripts takes a value of 0 or 1, indicating whether scripts should be excluded from rendering.

Similarly, you can reference a form picker property on your page:

@if (Model.FormId is Guid formId)
{
    @await Umbraco.RenderMacroAsync("renderUmbracoForm", new { FormGuid = formId, FormTheme = Model.FormTheme, ExcludeScripts = "1" })
}

When working with the Block List editor, the editor experience is enhanced by defining a label for the appearance of the Block.

These labels can contain AngularJS filters.

From Forms 10.2, a filter umbFormsFormName is available for use.

If you add a reference to a property containing a form to the block's label, it will render with the form's Id.

For example, assuming a property containing a picked form with an alias of contactForm:

{{contactForm}}

By using the filter as follows, the form's name will be displayed instead.

{{contactForm | umbFormsFormName}}

Umbraco Forms comes with a number of Field Types to allow you to request certain data in the forms that you design & build. This documentation is to guide specific details about field types that we ship that require some detail in how they work.

Date Picker

The date picker uses a front-end library called PikaDay.js to display a UI to pick dates from. We have added the support for the Pikaday date picker to be localized based on the page the form is rendered on. This displays the picked date in the correct locale. In JavaScript, we update a hidden field with a standard date format. This is done to send the date to the server, ensuring the record submission is stored in a standard format. This is to avoid locale mixing up dates.

To achieve this a new Razor partial view is included /Views/Partials/Forms/DatePicker.cshtml. Once on a page with a form that includes a Date Picker, it also includes the MomentJS library to assist with date locale formatting. Additionally, there are appropriate changes to Pikaday.js to support the locales. If you wish to use a different DatePicker component this is the file that you would customize to your needs.

Date Picker configuration of the year range

The DatePicker has one configuration setting to control the number of year shown. The default is 10 years which makes the picker unusable for picking birth dates.

Go to your appsettings.json and add:

  "Umbraco": {
    "CMS": {
        ...
    },
    "Forms": {
      "FieldTypes": {
        "DatePicker": {
          "DatePickerYearRange": 12
        }
      }
     }
    }

You can then change the DatePickerYearRange to a higher number (for example 100).

The File Upload field allows the users to upload a file along with the Form on your website.

In this article, you will find details about the configuration options you have for the File Upload field.

Predefined allowed File Types

You can choose to specify which files you want to allow the user to upload, when accessing the Form.

To allow only specific files:

1. Select the File Type checkbox the user should be able to upload.

2. Click Submit.

User Defined Allowed File Types

If the list of predefined file types do not include a specific file type, you can add additional ones.

To add new file type:

1. Type a file extension name in the User defined allowed file types field and click add.

2. Click Submit.

Expand the Form in the tree to view the Entries for each Form.

Entries Overview

When accessing the Entries viewer, you will be able to see all the entries submitted via the Form.

Viewing the Entries

By default, the list is filtered to show entries only from the past month. If you want to change the date range, pick the appropriate time period from the date picker. You can also filter the entries by specific words using the Search field on the left.

Clicking on the first field for each record in the list will open the full set of information recorded for the form entry. Next and previous buttons allow you to navigate through the entry list.

Editing the Entries

If configured via the permissions model and supported by the version of Umbraco Forms you are running, entries may be editable via the backoffice. If available, click the Edit button to switch the read-only view of an entry to an editable one and Save to record the changes. An audit trail will show who and when updates on the entry were made.

Validation will operate as is configured for the form in terms of mandatory fields and those that must match a particular pattern. Conditional display of fields is not supported.

Exporting Entries

To export all the entries from your Form:

1. Go to the Forms section.

2. Navigate to the Entries you wish to export.

3. Click Export in the top-right corner of the screen.
4. The Export dialog opens. Choose a format such as Microsoft Excel to export the Form records to.
5. Click Done.

If you have fields that allow the user to upload files within your form, you will also have the option to download a zip file containing these files. You can either download the files in the structure that they are stored on the web server's disk. Or you can download them organised by entry, so it's easier to match up the entry listed in the spreadsheet download with the uploaded file(s).

Record Actions

When selecting entries, it is possible to execute Actions. To select an entry, click anywhere on the entry.

Select at least 1 record to see the available actions in the top-right corner. By default, there are 2 possible actions:

• Approve

• Delete

There are some default prevalue source types that can be used.

Here is a quick overview of them:

• Get values from textfile

  Upload a textfile that contains the prevalues. Each prevalue should have its own line in the file. Once the file has been uploaded, you can find it in ~/wwwroot/App_Data/UmbracoForms/Data/PreValueTextFiles/{GUID} where the {GUID}is replaced with the pre-value ID.

• Umbraco Documents

  Allows to use content nodes from a specific source as prevalues. You can define the root node by either

  • Choosing a node directly from the Content tree or

  • Using XPath

    Additional settings can be applied:

    • Select Use current page as root instead of choosing a specific root node. The preview is not available when this setting is enabled.

    • Select a specific Document type, if the selected root node contains a different Document Type.

    • Select to include Grand children of the selected root node.

• SQL Database

  Connect to a OleDB compatible database table and construct a prevalue source from it. Once selected, it will be editable from the Forms interface.

  The following configurations need to be set:

  • Connection string (either choose one from your web.config or add another from a textfield)

  • Connection String from configuration

  • Table Name

  • Key Column

  • Value Column

• Umbraco Data Type Prevalues

  Choose an Umbraco Data Type to use its configured prevalue collection.

  In the example below, the prevalue collection from a Data Type called Home - Font - Radio button is used:

This documentation platform covers only major versions of the Umbraco Forms since Umbraco 9+. If you are using an older version of Umbraco Forms, you will need to go elsewhere.

The documentation for Umbraco 7 and 8 lives on our.umbraco.com.

Umbraco Forms comes with many default Field Types, also known as Answer Types. You can choose from these options when adding new fields to your Forms.

By default, the following Field Types are available:

• Short Answer: A textbox allows up to 250 characters.
• Long Answer: A bigger text field that allows multiline text and more than 250 characters.
• : Displays a picker that allows the user to select a date.
• Checkbox: Displays a single checkbox that can be checked or not.
• : Allows user to select and upload a local file.
• Password: Allows to type a password. The input is not visible when typing.
• Multiple Choice: Displays a list of items with a checkbox for each item where the user can select multiple options.
• Data Consent: A field for the purpose of asking for data consent. By default, this field is added to all new forms created with Forms version 6+.
• Dropdown: Displays a list of items in a drop down box where the user can select a single option.
• Single Choice: Displays a list of items with a radio button for each item where the user can select a single option.
• Title and Description: Displays a read-only title and description for a set of form fields.
• Rich Text: Displays read-only formatted text that can be used to provide additional information and links within a form.
• Hidden: A hidden field allows developers to include data that cannot be seen or modified by users when a Form is submitted.
• : The field displays a single checkbox for the user to select in order to validate the Form.
• : This field returns a score for each request without user interaction. The score is based on user interactions with the site and enables you to take an appropriate action for your site based on the score.

In this article, you can learn how to add extra functionality to your Form by attaching workflows.

Workflows are a way of defining actions after your Form is submitted like sending an email or creating a content node.

Default Workflow

By default, when a Form is submitted the record data is stored in the database. This can be configured in the of the Forms settings.

The behavior to display a message to the user who submitted the form can be configured by clicking on the built-in first workflow step. This step is labelled Submit message/Go to page, and it can also configure the redirection to another page.

If a value is selected for Go to page, it will be used to redirect to that page once the form has been submitted.

If no value is selected, the message in Message on submit is displayed to the user on the same page, instead of the form fields. This is implemented via a redirect to the current page, ensuring that the form can't be accidentally resubmitted.

By default, the message is created and rendered in plain text. If you need to add formatting to the message, toggle the Format message in rich text button.

Video Tutorial

Adding a Workflow

At the bottom of your Form, a default workflow is already attached to the Form, as well as an option to configure the workflows.

Clicking Configure workflow will give you the option to configure existing workflows, as well as setup new ones.

Choose a Workflow

A new workflow can be of different types and Umbraco Forms ships with a few default ones. You can find an overview of the types in the article.

Update Type-specific Settings

Once the Workflow Type has been selected, you will need to configure the workflow. There are different settings depending on the type that has been selected.

To use data from the submitted Form in your workflow, head over to the article and learn more about how that's done.

Configuring Condition on a Workflow

You can apply conditions to a workflow to ensure it only triggers under specific circumstances. You could as an example enable a condition that enables sending an email only if an email is added.

Select Enable conditions to open the condition editor. In the condition editor, you will see options to create logic that determines when the workflow should run. The condition is generally based on the values of the form fields.

For example: You have a form with a dropdown field labeled Preferred Contact Method with options such as Email and Phone. You can set up a workflow that sends an email notification only when the user selects Email.

Now, this email notification will only be sent when the user selects Email as their preferred contact method.

Fill in the rest of the settings and click Submit. The workflow is added to your Form and displayed at the bottom of the page.

Workflow Processing

When a form is submitted, any workflows associated with the "submit" stage of the form will run sequentially in the configured order. The record is stored after these workflows are completed, and as such they can make changes to the information recorded.

Similarly, approval of a form entry, whether automatic or manual, will trigger the execution of the workflows associated with the "approve" stage.

If a workflow encounters an unexpected error, it will silently fail from the perspective of the user submitting the form. The exception along with the other details of the failed operation is recorded to the log.

From Umbraco Forms versions 8.13.0 and 10.1, an audit trail has been made available. In the list of entries for a form, a summary is presented that shows how many workflows were executed, and how many were successful:

For each entry, in the backoffice a table can be viewed that shows each of the workflows and the success, or otherwise, of the operation.

For any workflows that did not complete successfully, a "Retry" link is available to trigger the workflow again. This is useful for example if there was a temporary infrastructure issue that perhaps prevented an email going out. You would be able to retrigger the workflow once the issue is resolved.

Forms output some JavaScript which is by default rendered right below the markup.

In many cases, you might prefer rendering your scripts at the bottom of the page. For example, before the closing </body> tag. This generally improves site performance.

In order to render your scripts where you want, you need to add a snippet to your template. Make sure you add it below your scripts, right before the closing </body> tag.

By default, Forms uses TempData for tracking the forms rendered on a page. The stored values are used when rendering the form scripts and associated data.

The following snippet should be used.

If you have changed the configuration value TrackRenderedFormsStorageMethod to use HttpContext.Items, the snippet is:

Read more about this configuration option in the article.

If you prefer to use a tag helper, that's an option too.

Firstly, in your _ViewImports.cshtml file, ensure you have a reference to the Umbraco Forms tag helpers with:

Then instead of reading from TempData and invoking the view component directly, you can use:

This will use the appropriate storage method that you have configured.

Enabling ExcludeScripts

If you do not want to render the associated scripts with a Form, you need to explicitly say so. You need to make sure ExcludeScripts is checked/enabled, whether you are inserting your Form using a macro or adding it directly in your template.

To enable ExcludeScripts:

• Using the Insert Form with Theme macro:
• While inserting Forms directly in your template:

When creating a text field in Umbraco Forms, a validation pattern in the form of a regular expression can be applied. Default patterns can be removed or re-ordered, and custom ones created and added.

Provided patterns

Umbraco Forms ships with three patterns: number, email, and URL. The class names are Number, Email, and Url respectively, and all are found in the Umbraco.Forms.Core.Providers.ValidationPatterns namespace.

Creating a custom validation pattern

To create a custom format function, create a class that implements IValidationPattern. You will need to initialize five properties:

• Alias - an alias that should be unique across the patterns and is typically camel-cased with no spaces.

• Name - the name of the pattern that will be visible in the backoffice.

• LabelKey - as an alternative to providing a name, a translation key can be provided. This will be used to look-up the name in the correct language for the backoffice user.

• Pattern - the regular expression pattern.

• ReadOnly - a flag indicating whether the pattern can be edited in the backoffice.

The following example shows the implementation of a pattern for a United Kingdom postcode (credit for the to at StackOverflow).

Registering the validation pattern

As with other provider types, the validation pattern needs to be registered. There are options to add, remove, and re-order patterns.

An example registration using the IUmbracoBuilder is shown below:

Using the pattern

With the pattern registered it will be available for selection by editors in the backoffice when they create validation for fields supporting this feature.

Umbraco Forms is a commercial product. You have a 14-day free trial to try out the product. After your trial expires, you'll need to have a valid license to keep using the product on your site.

How does it work?

Licenses are sold per domain and will also work on all subdomains. With every license, you will be able to configure two development/testing domains.

Example

Let's say that you have a license configured for your domain, mysite.com, and you've configured two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.mysite.com

• www.mysite.com

• mysite.com.local

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

There are a few differences as to what the licenses cover:

• A single license covers the installation of Umbraco Forms in 1 production domain, as well as in 2 development domains.

• The production domain includes all subdomains (e.g. *.mysite.com), as well as the .local extension (e.g. mysite.com.local).

• The development domains work with or without the www subdomain.

• The license allows for an unlimited number of forms.

• The license also includes localhost as a valid domain.

If you have multiple domains pointing at the same installation, you have the option to purchase and add additional domains to your license.

Additional domains can be purchased from your account on Umbraco.com. Each additional domain includes 1 live domain and 2 development/testing domains.

Configuring your license

You can look at the pricing, features, and purchase the license on the Umbraco Forms page.

When you've bought a license you need to configure it with your domains. You can either configure your license right away or you can do it later by visiting your account on Umbraco.com.

Reconfiguration of domains

Once a license has been configured with the domains, it is not possible to reconfigure them. An exception is when there is a mistake in the domain URL. As reconfiguration is not possible, you will either need to purchase an additional domain or a new license.

Installing your license

Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.

1. Download your license from your Umbraco.com account - this will give you a .lic file

2. Place the file in the /umbraco/Licenses directory in your Umbraco installation

The .lic file must be placed in the /umbraco/Licenses directory to be registered by Umbraco Forms. If the file isn't placed correctly, the application will automatically switch to trial mode.

Multiple license files

You can install multiple Umbraco Forms license files without merging them. Place each license file in the /umbraco/Licenses directory (or an alternative location). Each file should begin with umbracoForms, for example, umbracoForms.example1.lic and umbracoForms.example2.lic. This setup allows your installation to recognize multiple licensed domains.

Alternative license location

If you can't include the license file in the /umbraco/Licenses directory for any reason, it is possible to configure an alternative location for the file.

It can be configured in the Umbraco installation's appSettings.json file by adding the following appSetting. The value contains the path of your custom license directory relative to the root of your Umbraco installation.

{
  "Umbraco": {
    "Licensing": {
        "Directory": "~/custom-licenses-folder/"
    }
  }
}

Sometimes you might have a field in your Form, that you want to show only if the user has entered a specific value in another field.

You can achieve this setting by using conditional logic on Fields.

Example

Take a look at the following:

In this case, it makes sense to only show the email or phone field when the corresponding option is selected in the How should we contact you? field.

To enable conditions for the Email and Phone fields, do the following:

1. Click the cog wheel next to the Email and Phone field. The Edit question dialog opens.

2. Select Enable Conditions in the Conditions section.
3. Enabling the condition field displays more options:
4. Set the appropriate conditions and click Submit.

Action and Logic Types

There are two Action Types:

• Show: the field will be displayed if the rules match

• Hide: the field will be hidden if the rules match

Next up, you'll need to specify the Logic Type. This setting is only important if you have multiple rules.

• All: All of the rules must match

• Any: Any of the rules may match

Adding a new condition

When adding a new condition, you'll need to select the field where you want to evaluate the value and can select an operator.

In this example, we only want to show the Phone field if the value of the How should we contact you field is Phone.

Similarly, you can display the Email field, if the value of the How should we contact you field is Email. You can see the conditions added to each field in the Forms designer:

Result

When both the conditions have been set as shown above, this is how it will look on the frontend:

In this example, we have only selected Phone but it is possible to choose both Phone* and Email and display both the fields.

Conditions for Pages and Fieldsets

As well as showing or hiding a field based on conditions, you can also apply conditions to groups of fields (known as fieldsets) or to pages. The process is the same as described above.

When applying a condition to a page, effectively you are controlling the display of the submit button (for a single-page form) or the next/previous buttons (available on multi-page forms). In this way you can ensure that the entry so far is complete before accepting it or allowing the user to move onto the next page.

Conditions for Dates

You can apply conditions to dates as well as strings. When you use the date picker field, you can set a condition if a submitted date is greater/less than a specific date.

Umbraco Forms supports Themes, allowing forms to be customized in a much simpler manner.

Creating a Theme

To create a theme, you need to create a folder at /Views/Partials/Forms/Themes/. The name of the folder is the name of theme that will be visible in the backoffice when choosing it.

Copy the explicit files you wish to override in your theme, it may be a single file or all files from the default theme folder. Make the necessary changes you desire to CSS class names, markup etc.

Obtaining the Default Theme Files

For Umbraco 9 and previous, it's straightforward to copy the files you need from the default theme folder. We highly recommend that you never customize any files found in the default themes folder. There is a risk that any customizations to these files will be lost with any future upgrades you do to Umbraco Forms. Umbraco 10+ distributes these files as part of a Razor Class Library, so you won't find them on disk. Instead you should download the appropriate zip file for your Forms version and extract the ones you need.

You can obtain the latest version of the Forms default theme from the following links:

• 10.0.0-rc1

• 10.1.0

• 10.2.0

• 10.2.4

• 10.3.0

• 10.5.0-rc1

• 10.5.1

• 10.5.2

• 10.5.3

• 10.5.5

• 10.5.6

You should use the theme available for the highest version that's less or equal to the version of Forms you have installed. For example, when using Umbraco Forms 10.4.0, and no file for that version is available use version 10.3.0 instead.

Amending Theme Files

If adding or amending client-side scripts, you need to copy the Script.cshtml file from the default themes folder. In your copy, amend the .js references to reference your own script files.

Using a Theme

To use a theme with a Form use the "Insert Form" macro where you will be presented with the options of the form you wish to insert along with an option to pick a theme. This displays the list of theme folders found at Views/Partials/Forms/Themes.

When you are rendering your form directly in your template, you need to specify your theme by filling out the FormTheme attribute:

@await Umbraco.RenderMacroAsync("renderUmbracoForm", new {FormGuid="1ec026cb-d4d3-496c-b8e8-90e0758c78d8", FormTheme="MyFormTheme", ExcludeScripts="0"})

If you do not pick and/or set a theme, the default theme will be used to render the form.

Theme Fallbacks

When using a theme, Umbraco Forms will try to use a view from the theme folder, but then fallback to the same view in the default theme folder if it can't be found. This allows you to create a theme by only modifying the files necessary to make your customizations.

Files which can be overridden:

• Render.cshtml (overrides the entire form - usually not needed)

• Form.cshtml (overrides the generation of the fields on the current page)

• Script.cshtml (overrides the way files are included with the form)

• /Fieldtypes/FieldType.*.cshtml (overrides a specific view for a field)

Helper Methods

SetFormThemeCssFile

Sets the primary form theme stylesheet path. This overrides an already assigned stylesheet and will be rendered out when inserting the form into the page

Html.SetFormThemeCssFile(Model, "~/App_Plugins/UmbracoForms/Assets/Themes/Default/style.css")

AddFormThemeScriptFile

Add a JavaScript file path to include on form render

Html.AddFormThemeScriptFile("~/App_Plugins/UmbracoForms/Assets/themes/default/umbracoforms.js");

SetFormFieldClass

Adds a class to the form field HTML element of a given type. If no type is given, it will add the class to all fields

// Applies the CSS class 'form-control' to all fields that GetFormFieldClass uses in FieldType views
@Html.SetFormFieldClass("form-control")

// Applies the CSS class 'some-other-class' for the FieldType of the name 'Password'
@Html.SetFormFieldClass("some-other-class", "Password")

GetFormFieldClass

Retrieves all classes for a given field type, used when rendering form fieldtype partial views

class="@Html.GetFormFieldClass(Model.FieldTypeName)"

SetFormFieldWrapperClass

Adds a class to the div element wrapping around form fields of a given type. If no type is given, it will add the class to all fields

// Applies the CSS class 'form-group' around all fields, labels & help texts
@Html.SetFormFieldWrapperClass("form-group")

// Applies the CSS class 'some-other-class' for the FieldType of the name 'Password'
@Html.SetFormFieldWrapperClass("some-other-class", "Password")

GetFormFieldWrapperClass

Retrieves all wrapper classes for a given field type, used when rendering form fields. This class wraps both label, help-text and the field itself in the default view

class="@Html.GetFormFieldWrapperClass(f.FieldTypeName)"

With Umbraco Forms, it is possible to customize the output markup of a Form, which means you have complete control over what Forms will display.

Customizing the Default Views

The razor macro uses some razor views to output the Form:

• 1 view for each fieldtype

• 1 view for the scripts

• 1 view for the rest of the Form

You can find the default views in the ~\Views\Partials\Forms\Themes\default folder.

To avoid your custom changes to the default views from being overwritten, you need to copy the view you want to customize into your theme folder, e.g. ~\Views\Partials\Forms\Themes\YourTheme, and edit the file in YourTheme folder.

Form.cshtml

This is the main view responsible for rendering the Form markup.

The view is separated into two parts, one is the actual Form and the other will be shown if the Form is submitted.

This view can be customized, if you do so it will be customized for all your Forms.

Script.cshtml

This view renders the JavaScript that will take care of the conditional logic, customization won't be needed here.

FieldType.*.cshtml

The rest of the views start with FieldType, like FieldType.Textfield.cshtml and those will output the fields. There is a view for each default fieldtype like textfield, textarea, checkbox, etc)

Contents of the FieldType.Textfield.cshtml view (from the default theme):

@model Umbraco.Forms.Mvc.Models.FieldViewModel
@using Umbraco.Forms.Mvc

<input type="text"
    name="@Model.Name"
    id="@Model.Id"
    class="@Html.GetFormFieldClass(Model.FieldTypeName) text"
    value="@Model.ValueAsHtmlString"
    maxlength="500"
    @{if(string.IsNullOrEmpty(Model.PlaceholderText) == false){<text>placeholder="@Model.PlaceholderText"</text>}}
    @{if(Model.Mandatory || Model.Validate){<text>data-val="true"</text>}}
    @{if (Model.Mandatory) {<text> data-val-required="@Model.RequiredErrorMessage"</text>}}
    @{if (Model.Validate) {<text> data-val-regex="@Model.InvalidErrorMessage" data-val-regex-pattern="@Html.Raw(Model.Regex)"</text>}}
/>

Umbraco Forms uses ASP.NET Unobtrusive Validation which is why you see attributes like data-val and data-val-required.

This can be customized but it's important to keep the ID of the control to @Model.Id since that is used to match the value to the Form field. For fields that are conditionally hidden, without an ID of @Model.Id the control won't be shown when the conditions to show the field are met. An ID needs to be added to text controls such as headings and paragraphs.

The view model for the partial view for a field is FieldViewModel. This defines properties that may be useful when creating new themes or custom fields, some of which are shown in the code samples above. Others include:

• AdditionalSettings - a dictionary of the settings keys and values populated for the form field. These can be retrieved in typed form by key using e.g. Model.GetSettingValue<int>("MaximumLength", 255);.

The following are available on the model but only populated for fields that support file upload:

• AllowAllUploadExtensions- a boolean indicating whether all file extensions are permitted for upload.

• AllowedUploadExtensions- a collection of strings indicating the file extensions that are permitted for upload.

• AllowMultipleFileUploads- a boolean indicating whether selecting multiple files for upload is allowed.

Customizing for a Specific Form

It is also possible to customize the markup for a specific Form.

You will need to create folder using the ID of the Form: ~\Views\Partials\Forms\{FormId} (find the id of the Form in the URL when you are viewing the Form in the backoffice.)

As an example if your Form ID is 0d3e6b2d-db8a-43e5-8f28-36241d712487 then you can overwrite the Form view by adding the Form.cshtml file to the directory. Start by copying the default one and then making your custom changes: ~\Views\Partials\Forms\0d3e6b2d-db8a-43e5-8f28-36241d712487\Form.cshtml.

You can also overwrite views for one or more fieldtypes by adding the views to the Fieldtypes folder: ~\Views\Partials\Forms\0d3e6b2d-db8a-43e5-8f28-36241d712487\Fieldtypes\Fieldtype.Textfield.cshtml.

In this article, you will find information about accessing the Forms Settings and the validations available to customize your Form.

To access the Form Settings:

1. Navigate to the Forms section.

2. Open a Form you wish to customize.

3. Click Settings in the top-right corner of the screen.

Settings Options

The following options are available in Forms Settings:

Store Records

By default, all submitted records are saved in the database. This option allows you to view and export the saved records from the queries overview. If you do not want to store data (due to policies in your organization), you can uncheck the box.

Disabling this option will prevent database records from being stored, but any file uploads made as part of the form submission will still be retained. If you do not want the files to be stored, ensure that any process or method used to process, move, or copy them to a different location also removes the file.

Captions

Customize the labels of the Submit, Next, and Previous buttons used in your Form.

Styling

Set a stylesheet to give your Form custom styling. You have an option to disable the default styling. Enabling the Disable default stylesheet option will prevent a default stylesheet to be added to the pages where the Form is placed.

Validation

Define a message that is displayed when a field is mandatory, when a value is not supplied, or when the value is invalid.

The following Validations are available:

Autocomplete

The autocomplete setting for the overall form can be changed from the default of "None" to "On" or "Off". Setting this explicitly will control how the browser offers automatic prompts to the user when completing the form.

Moderation

Enabling this feature allows the moderator to manage the approval status of a form. This can be used in a number of scenarios. For example, if the form submission will be publicly shown, you can control which are published.

Fields displayed

By default, a constant set of fields are displayed when form entries are shown in a list. You will see the first three fields in the form, plus some system information like the record state and the date it was created.

To customize this, turn off the "Display default fields" option and select the ones you wish to display.

Date retentions

To help protect site visitor privacy, rules can be configured in this section for the automatic deletion of submissions. You can set how long to retain records for each state (submitted or approved).

A background service that carries out the actual removal of records needs to be . If that is not running, a notification will be displayed.

Prevalue sources are a way to pre-define and/or retrieve a list of items from a certain source. They can be added in any field types that include some kind of list like Dropdown and Multiple/Single Choice lists.

Setting up a Prevalue Source

Prevalue sources can be managed in the Prevalue sources folder available in the Forms section.

To set a prevalue source:

1. Navigate to the Forms section.

2. Right-click the Prevalue sources folder and select Create.

3. A new page opens in the right-side of the editor where you'll need to setup and configure your prevalue source.

4. Enter a Name.

5. Select the type of prevalue source from the Type drop-down. For more information on the different default types, see the article.

Configuring the Prevalue Source

Depending on the Type you choose, you'll need to provide some additional settings:

1. In this walk-through, we will select Get values from textfile from the Type drop-down.

2. Now, provide a file containing the list to use as prevalues. For example: A .txt file containing the following values:

3. Select Pick File and choose the text file you created.

4. Once the text file is uploaded, click Save to save the prevalue source.

5. If the file is successfully uploaded and validated, you will see an overview of the values in a tabular format.

If you would like to have different values presented to your users from the value stored, you can provide two values per line, separated with a vertical bar (|), e.g.:

In this case the user would pick from a list showing the captions, but the single integer values would be stored with the record.

This can be useful if the recorded entries are used in any subsequent workflows or business processes, where particular values, that aren't appropriate for the user to select from, are required.

Defining Cache Options for the Prevalue Source

Sometimes retrieving the list of options for a prevalue source can be an expensive operation. If the source depends on data from external systems, it could be that the list changes regularly or rarely.

Given the variation here, we allow you to select an appropriate level of caching for the list of options.

You can choose between:

• No Caching - no caching will be applied and the list of options will be retrieved from source on every request. You will likely only want to choose this option if the information changes frequently and it's important that the latest is presented to website visitors.

• Cache For Specified Time - the list will be cached for the period of time provided.

• Cache With No Expiry - the list will be cached on first request and not retrieved again until either the prevalue source is edited or the website is restarted. This is most appropriate to use for information held within the prevalue source data itself (such as when uploading a text file).

Attaching a Prevalue Source to a Field

Once a prevalue source has been created, it can be used while building Forms in the Forms designer.

Example: Let's add a Multiple Choice field type in our Form.

If there is at least one prevalue source defined in the project, the Prevalues source will contain a dropdown from where you can choose the predefined value.

Once you have selected the prevalue source, the values are rendered in the Forms designer from the attached source.

Umbraco Forms includes some helper methods that return records of a given Form, which can be used to output records in your templates using razor.

Available Methods

The methods can be found by injecting the Umbraco.Forms.Core.Services.IRecordReaderService interface. For performance reasons, all these methods are paged.

GetApprovedRecordsFromPage

Returns all records with the state set to approved from all Forms on the Umbraco page with the id = pageId .

GetApprovedRecordsFromFormOnPage

Returns all records with the state set to approved from the Form with the id = formId on the Umbraco page with the id = pageId as a PagedResult<IRecord>.

GetApprovedRecordsFromForm

Returns all records with the state set to approved from the Form with the ID = formId as a PagedResult<IRecord>.

GetRecordsFromPage

Returns all records from all Forms on the Umbraco page with the id = pageId as a PagedResult<IRecord>.

GetRecordsFromFormOnPage

Returns all records from the Form with the id = formId on the Umbraco page with the id = pageId as a PagedResult<IRecord>.

GetRecordsFromForm

Returns all records from the Form with the ID = formId as a PagedResult<IRecord>.

The returned objects

All of these methods will return an object of type PagedResult<IRecord> so you can iterate through the IRecord objects.

The properties available on a IRecord are:

In order to access custom Form fields, these are available in the RecordFields property. Furthermore there exists an extension method named ValueAsString on IRecord in Umbraco.Forms.Core.Services, such that you can get the value as string given the alias of the field.

This extension method handle multi value fields by comma separating the values. E.g. "A, B, C"

Sample razor script

Sample script that is outputting comments using a Form created with the default comment Form template.

Umbraco Forms functionality can be extended in different ways. In this section we focus on techniques available to a back-end/C# developer.

For front-end extensions, specifically via theming, see the section.

Developing Custom Providers

The Forms package comes with many field, workflow, and other built-in types. If you have a requirement that isn't served by any of these, you can create and develop your own.

Many features of Forms use a provider model, which makes it quicker to add new parts to the application.

The model uses the notion that everything must have a type to exist. The type defines the capabilities of the item. For instance a Textfield on a form has a FieldType, this particular field type enables it to render an input field and save text strings. The same goes for workflows, which have a workflow type, datasources which have a datasource type and so on. Using the model you can seamlessly add new types and thereby extend the application.

It is possible to add new Field types, Data Source Types, Prevalue Source Types, Export Types, and Workflow Types.

A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved.

The concept of provider settings, common to the field and other types, is also discussed in this section.

Data Source Types

A data source type enables Umbraco Forms to connect to a custom source of data. A data source consists of any kind of storage if it is possible to return a list of fields Umbraco Forms can map values to. For example: a Database data source can return a list of columns Forms can send data to. This enables Umbraco Forms to map a form to a data source. A data source type is responsible for connecting Forms to external storage.

A prevalue source type connects to 3rd party storage to retrieve values. These values are used on fields supporting prevalues. The source fetches the collection of values.

A workflow can be executed each time a form changes state (when it is submitted for instance). A workflow is responsible for executing logic which can modify the record or notify 3rd party systems.

Export types are responsible for turning form records into any other data format, which is then returned as a file.

Custom magic string format functions to add to the can be created in code.

When creating a text field in Umbraco Forms, a validation pattern in the form of a regular expression can be applied. Default patterns can be removed or re-ordered, and custom ones created and added.

Handling Forms Events

Another option for extension via custom code is to hook into one of the many events available.

Form events are raised during the submission life cycle and can be handled for executing custom logic.

When a new form is created, the default behavior is to add a single workflow. This workflow will send a copy of the form to the current backoffice user's email address.

A single "data consent" field will also be added unless it has been disabled via configuration.

It's possible to amend this behavior and change it to fit your needs.

Responding to State Values

In the course of submitting a form, Umbraco Forms will set values in TempData and/or HttpContext.Items, that you can use to customize the website functionality.

Customizing Post-Submission Behavior

Whether displaying a message or redirecting, a developer can customize the page viewed after the form is submitted based on the presence of TempData variables.

One variable with a key of UmbracoFormSubmitted has a value containing the Guid identifier for the submitted form.

A second variable contains the Guid identifier of the record created from the form submission. You can find this using the Forms_Current_Record_id key.

In order to redirect to an external URL rather than a selected page on the Umbraco website, you will need to use a . Within this workflow you can set the required redirect URL on the HttpContext.Items dictionary using the key FormsRedirectAfterFormSubmitUrl (defined in the constant Umbraco.Forms.Core.Constants.ItemKeys.RedirectAfterFormSubmitUrl).

For example, using an injected instance of IHttpContextAccessor:

This builds on the "" chapter

Umbraco Forms can be used to replace placeholders within form elements with values from different sources. Sources include the HTTP request or the Umbraco page where the form is hosted.

These values can be formatted using .

Filter functions for common operations such as truncating a string or formatting a date or number are provided. It's also possible to create custom ones in code.

Creating a custom format function

To create a custom format function, create a class that implements IParsedPlaceholderFormatter.

The FunctionName property provides the name of the function that will be used within the form's magic string.

The FormatValue property parses the provided value and arguments and returns the formatted value as a string.

The following example shows the implementation of a function that bounds an integer value. It takes two arguments, a minimum and maximum value. If the value read from the magic string source is numeric, and fits within the two bounds, it is returned. Otherwise, either the minimum or maximum value is returned depending on whether the value is lower or higher than the bounds respectively.

Registering the custom format function

As with other provider types, the custom function needs to be registered. An example registration using the IUmbracoBuilder is shown below:

Using the custom format function

The format function can be used within a form's magic string in the same way as the ones provided with Umbraco Forms.

For the example provided, it would be used like this:

can be configured to appear alongside forms in the Umbraco Forms backoffice section.

They will appear after the default "Design" and "Settings" apps when editing a form in the backoffice:

A content app such as the following would display only in the forms section:

Within the /App_Plugins/TestFormsContentApp/ folder we need the client-side files, for which an example is shown below:

package.manifest:

testformscontentapp.html:

testformscontentapp.controller.js:

Finally, it needs to be registered via a composer:

This builds on the "adding a type to the provider model" chapter

Add a new class to your project and have it inherit from Umbraco.Forms.Core.WorkflowType, implement the class. For this sample we will focus on the execute method. This method process the current record (the data submitted by the form) and have the ability to change data and state.

using Serilog;
using System;
using System.Collections.Generic;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Data.Storage;
using Umbraco.Forms.Core.Enums;
using Umbraco.Forms.Core.Persistence.Dtos;
using Microsoft.Extensions.Logging;
using Umbraco.Core.Composing;

namespace MyFormsExtensions
{
    public class TestWorkflow : WorkflowType
    {
        private readonly ILogger<TestWorkflow> _logger;

        public TestWorkflow(ILogger<TestWorkflow> logger)
        {
            _logger = logger;

            this.Id = new Guid("ccbeb0d5-adaa-4729-8b4c-4bb439dc0202");
            this.Name = "TestWorkflow";
            this.Description = "This workflow is just for testing";
            this.Icon = "icon-chat-active";
            this.Group = "Services";
        }

        public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context)
        {
            // first we log it
            _logger.LogDebug("the IP " + context.Record.IP + " has submitted a record");

            // we can then iterate through the fields
            foreach (RecordField rf in context.Record.RecordFields.Values)
            {
                // and we can then do something with the collection of values on each field
                List<object> vals = rf.Values;

                // or get it as a string
                rf.ValuesAsString(false);
            }

            //Change the state
            context.Record.State = FormState.Approved;

            _logger.LogDebug("The record with unique id {RecordId} that was submitted via the Form {FormName} with id {FormId} has been changed to {RecordState} state",
               context.Record.UniqueId, context.Form.Name, context.Form.Id, "approved");

            return WorkflowExecutionStatus.Completed;
        }

        public override List<Exception> ValidateSettings()
        {
            return new List<Exception>();
        }
    }
}

Information available to the workflow

Record information

The Execute() method gets a WorkflowExecutionContext which has properties for the related Form, Record, and FormState. This parameter contains all information related to the workflow.

The Record contains all data and metadata submitted by the form. As shown in the example above, you can iterate over all RecordField values in the form. You can also retrieve a specific record field by alias using the following method:

RecordField? recordField = context.Record.GetRecordFieldByAlias("myalias");

Having obtained a reference to a record field, the submitted value can be retrieved via:

var fieldValue = recordField.ValuesAsString(false);

The ValuesAsString will JSON escape the result by default. If you do not want this escaping to occur, pass false as the parameter.

If the field stores multiple values, they are delimited with a comma. In many cases, you can safely split on that delimiter to obtain the individual values. However, this can lead to issues if the prevalues being selected also contain commas. If that's a concern, the following extension method is available in Umbraco.Forms.Core.Extensions to correctly parse the selected prevalues:

IEnumerable<string> selectedPrevalues = recordField.GetSelectedPrevalues();

Form and state information

The Form references the form the record is from and FormState provides its state (submitted or approved).

Other context, such as the current HttpContext, if needed can be passed as constructor parameters (for example: the HttpContext can be accessed by injecting IHttpContextAccessor).

Registering the workflow type

To use the new workflow type, you will need to register it as part of application startup.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Forms.Core.Providers;

namespace MyFormsExtensions
{
    public class Startup : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
                .Add<TestWorkflow>();
        }
    }
}

Umbraco Forms has a backoffice security model integrated with Umbraco users. Details are managed in the Users section of the backoffice, within a tree named Form Security.

User based permissions

Within the Form Security tree, each user with a backoffice account is listed. Clicking on a user allows each functional permission to be set:

• Manage forms - user can create and edit form definitions

• View entries - user can view the submitted entries

• Edit entries - user can edit the submitted entries

• Manage datasources - user can create and edit datasource definitions

• Manage prevalue sources - user can create and edit prevalue source definitions

For further control, each form is listed and the user can be granted or denied access to each as appropriate.

As new forms are created, users will automatically be granted access to them, unless the configuration setting DefaultUserAccessToNewForms has been set to a value of Deny.

Start folders

When form definitions are configured for storage in the database, it allows for the creation of folders to group forms within. It's also possible to define one or more start folders for a user. This is done in order to limit their access to a subset of the forms available.

If no start folders are selected, the user will be able to access all forms in the backoffice according to their permissions.

If a single start folder is selected, that will act as the root of the tree view of forms. The user will have access to all folders and forms below that selected folder.

If more than one start folder is selected, they will appear underneath the root of the tree view of forms. The user will have access to only those folders and their descendant folders and forms.

User group based permissions

A new model was introduced allowing for the management of permissions at the level of user groups. Particularly for installations with a large number of users, we expect this to be a more useful setup and require less ongoing administration.

When user groups are involved in permissions, access to a particular resource or feature is determined by the following:

• If the user has a specific user permission set, it is used in preference to anything set on the user groups they are a part of.

• If the user doesn't have a specific user permission set, they are granted access if at least one of the user groups they are part of has access.

To enable the feature, it's necessary to update the ManageSecurityWithUserGroups configuration setting to true.

With that in place the Form Security tree divides into three sub-trees:

• Under Group Permissions, each user group is listed and the same settings as described above for individual users can be set here.

• Under User Permissions, each user that has a specific user permission record is listed and can be managed. Records for users can be created or deleted via the tree's action menu.

As new forms are created, user groups with aliases listed in the GrantAccessToNewFormsForUserGroups configuration setting will be automatically given access. For example, with a value of admin,editor, the built-in Administrators and Editors groups would have access.

Start folders for user groups

Start folders are enabled for User Groups. They work in a similar way as the group based permissions described above:

• If the user has a specific user permission set, it is used in preference to anything set on the user groups they are a part of.

  • This means if the user has no start folders defined and the groups they are part of do, they will have access to the root of the Forms tree and be able to access all folders and Forms.

• If the user doesn't have a specific user permission set, they are granted access to all the unique folders the groups they are part of have access to.

  • If they are part of any group that has access to the forms section, permission to manage forms and no start folders defined, they will have access to the root of the Forms tree and be able to access all folders and Forms.

Migrating to user group based permissions

In introducing the user group based permissions, we've taken care to ensure a migration path. This is available for those existing installations running on older versions of Umbraco Forms. In that situation, we'd recommend the following approach.

• Upgrade to Umbraco 9.3.

• At this stage nothing will have changed in terms of the permissions model in use.

• Set the ManageSecurityWithUserGroups configuration value to true and the GrantAccessToNewFormsForUserGroups as appropriate for your setup.

• Via the Users > Form Security section, set the required permissions on each user group.

• Again at this point nothing will have changed with regard the effective permissions for each user, as they will currently all have an existing user permission record.

• Via Users > Form Security > User permissions, delete the permission records for each user.

• The effective permissions for each user will now be derived from their user groups.

• If you have any exceptions - where a particular user needs a particular combination of permissions that you can't or don't want to provide via the user groups - it's always possible to re-create a user permission record that will take precedence over the group based permissions.

Handling Sensitive Data in Umbraco Forms

Marking fields and properties as sensitive will hide the data in those fields for backoffice users that are not privy to the data. Built-in features are available to help you secure sensitive information. For more information, see the Sensitive data article.

The following sections covers how to grant or deny access to sensitive data for specific users and how to mark form questions as sensitive.

Assigning Users to the Sensitive Data Group

To allow users to view and handle sensitive data in Umbraco Forms, you must assign them to the Sensitive Data user group:

1. Navigate to the Users section in the Umbraco Backoffice.

2. Select the user you want to grant access to.

3. Click Choose in the Groups field under the Assign access section.

4. Select Sensitive Data from the list of User Groups.

5. Click Submit.

6. Click Save.

Marking Questions in Forms as Sensitive

Once the users are set up with the appropriate permissions, the next step is to identify which form fields should be marked as sensitive.

Marking a field as sensitive ensures that only authorized users in the Sensitive Data user group can access data from these fields.

To mark questions as sensitive, follow these steps:

1. Navigate to the Forms section in the Umbraco Backoffice.

2. Open the form you wish to configure (for example: Contact Form).

3. Click on the cogwheel icon next to the form field you want to secure.

4. Enable the Sensitive data setting for the field.

1. Click Submit.

2. Click Save.

In this article, you will find information about Umbraco Forms-related health checks that can be run from the Umbraco backoffice to ensure that your installation is running seamlessly.

Read the article to learn more about the feature in general.

Database Integrity Health Check

Running this health check will verify whether the database tables for the Umbraco Forms installation are all set up correctly with the proper data integrity checks.

In this section, you can learn more about the background for adding this check, as well as how to use and understand the results.

Background

With version 8.7, a health check was introduced to confirm the Umbraco Forms database tables are all set up with the expected data integrity checks - i.e. primary keys, foreign keys and unique constraints.

In most cases, you can expect them all to be in place without any developer intervention. For new installs, the database schema is initialized with all the necessary integrity constraints. And for upgrades, any new schema changes are automatically applied.

There remains the possibility though that not all will be in place for a particular installation. For example, this could happen if a constraint is added in a new version. It can't be added via an automated migration due to existing data integrity issues.

In particular, prior to version 8.7, there were a number of tables that weren't defined as strictly as they should be in this area. So we've added some primary key, foreign key and unique constraints with this version. If you've been running a version prior to this and are upgrading, these schema updates will be applied automatically unless there is existing data in the tables that prevent them from being added.

There shouldn't be - but without these constraints in place it's always possible for an application bug to exist that allows for example the creation of duplicate records, or the orphaning of records, that aren't correct. This is the reason for the constraints to exist, and why we want to ensure they are in place.

Running The Health Check

To run the health check:

1. Navigate to the Health Check dashboard in the Settings section in the Umbraco backoffice.

2. Click on the Forms button and select Check Group. You'll see a result that looks something like this:

If you have a full set of green ticks, then you're all good - and no need to read on!

If you have one or more red crosses though, that means a particular constraint wasn't able to be applied via the automatic schema migrations when you installed a new version of Umbraco Forms, due to existing data issues.

It isn't essential that they are resolved - the package can and does function correctly without them - but for reasons of ensuring data integrity and performance, it is recommended that they are.

Resolving Reported Problems

When Umbraco Forms installs an upgrade, it will attempt to apply any schema changes. If though, the update isn't essential, and it can't proceed due to existing data integrity issues, the failed update will be logged and then the rest of the migration will continue.

As well as in the log files, such issues will be visible via the health check and will need to be resolved by applying scripts directly to the database.

To support this, we provide the following SQL scripts:

• Apply database integrity schema changes for 8.7.0+ -

• Apply database integrity schema changes for 8.7.0+ (Forms in database tables) -

The first of these provides the SQL statements required to apply the schema updates for 8.7.0+ to the common Umbraco Forms tables. The second applies to those tables used for when Forms are stored in the database, and hence only need to be applied if that option is configured.

To take an example, let's say that via the health check results you can see that the "Unique constraint on table 'UFForms', column 'Key' is missing."

If you look in the SQL script you'll see that in order to apply this directly to the database, you would need to run the following SQL statement:

If you run it though, you'll see the reason why the migration that ran when Umbraco Forms was upgraded couldn't apply the change:

The constraint can't be applied if there are existing duplicate values, so first they need to be found and removed.

To find duplicate values in the 'Key' field in this table you can run the following SQL statement:

Running the statement above will list out the 'Key' fields that are duplicated in the table.

To see the full details of the duplicate records, you can use this query:

From the Id field you can identify the Form records that are duplicated and should be removed, and delete the records. To check you have found them all, run one of the above queries again, and confirm you find no records returned.

Finally you can run the ALTER TABLE... statement shown above to apply the constraint, and confirm via the health check that it's now in place.

By repeating similar steps as required, you'll be able to ensure that all recommended keys, constraints and indexes are in place.

If for any reason you wish to revert the changes - perhaps when testing these updates in a non-production environment - reversion scripts for all the 8.7 updates are also provided:

To support this, we provide the following SQL scripts:

• Revert database integrity schema changes for 8.7.0+ -

• Revert database integrity schema changes for 8.7.0+ (Forms in database tables) -

Umbraco Forms contains a built-in Get value from textfile that stores the uploaded text file into the physical file system (by default in umbraco\Data\UmbracoForms\PreValueTextFiles).

You can replace the default implementation by writing your own IPreValueTextFileStorage and registering that using e.g. builder.Services.AddUnique<IPreValueTextFileStorage, CustomPreValueTextFileStorage>() (in Startup.cs or a composer).

You can also use/inherit from PreValueTextFileSystemStorage to change the underlying IFileSystem that's used to store the prevalue text files.

Move files to Media file system

You can use the following composer to move the prevalue text files into the media file system. If the media file system is using Azure Blob Storage, this will remove the files from the local physical file system.

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your media storage. The final file path/URL will look like ~/media/PreValueTextFiles/{GUID}/{filename.txt} and be accessible from the browser.

Move files to Azure Blob Storage

First, install and configure the Forms storage container, for example by adding the following to your appsettings.json:

Next, add the following composer that adds the Forms storage container and stores the prevalue text files into Azure Blob Storage (in forms/PreValueTextFiles/{GUID}/{filename.txt}):

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your storage container. If you've disabled public access, the stored files are not accessible from the browser.

This page covers specific upgrade documentation for when migrating to major 8 and 10 of Umbraco Forms.

Version Specific Upgrade Notes History

Legacy version specific upgrade notes

You can find the version specific upgrade notes for versions out of support in the Legacy documentation on GitHub.

Form validation notification

Add a new class to your project as a handler for the FormValidateNotification notification:

using System.Linq;
using Microsoft.AspNetCore.Http;
using Umbraco.Cms.Core.Events;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Services.Notifications;

namespace MyFormsExtensions
{
    /// <summary>
    /// Catch form submissions before being saved and perform custom validation.
    /// </summary>
    public class FormValidateNotificationHandler : INotificationHandler<FormValidateNotification>
    {
        public void Handle(FormValidateNotification notification)
        {
            // If needed, be selective about which form submissions you affect.
            if (notification.Form.Name == "Form Name")
            {
                // Check the ModelState
                if (notification.ModelState.IsValid == false)
                {
                    return;
                }

                // A sample validation
                var email = GetPostFieldValue(notification.Form, notification.Context, "email");
                var emailConfirm = GetPostFieldValue(notification.Form, notification.Context, "verifyEmail");

                // If the validation fails, return a ModelError
                if (email.ToLower() != emailConfirm.ToLower())
                {
                    notification.ModelState.AddModelError(GetPostField(notification.Form, "verifyEmail").Id.ToString(), "Email does not match");
                }
            }
        }

        private static string GetPostFieldValue(Form form, HttpContext context, string key)
        {
            Field field = GetPostField(form, key);
            if (field == null)
            {
                return string.Empty;
            }


            return context.Request.HasFormContentType &&  context.Request.Form.Keys.Contains(field.Id.ToString())
                ? context.Request.Form[field.Id.ToString()].ToString().Trim()
                : string.Empty;
        }

        private static Field GetPostField(Form form, string key) => form.AllFields.SingleOrDefault(f => f.Alias == key);
    }
}

The handler will check the ModelState and Form field values provided in the notification. If validation fails, we add a ModelError.

To register the handler, add the following code into the startup pipeline. In this example, the registration is implemented as an extension method to IUmbracoBuilder and should be called from Startup.cs:

public static IUmbracoBuilder AddUmbracoFormsCoreProviders(this IUmbracoBuilder builder)
{
    builder.AddNotificationHandler<FormValidateNotification, FormValidateNotificationHandler>();
}

Service notifications

The services available via interfaces IFormService, IFolderService, IDataSourceService and IPrevalueSourceService trigger following notifications before or after an entity handled by the service is modified.

The "-ing" events allow for the entity being changed to be modified before the operation takes place, or to cancel the operation. The "-ed" events fire after the update is complete.

Both can be wired up using a composer and component:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<FormSavingNotification, FormSavingNotificationHandler>();
        }
    }

    public class FormSavingNotificationHandler : INotificationHandler<FormSavingNotification>
    {
        public void Handle(FormSavingNotification notification)
        {
            foreach (Form form in notification.SavedEntities)
            {
                foreach (Page page in form.Pages)
                {
                    foreach (FieldSet fieldset in page.FieldSets)
                    {
                        foreach (FieldsetContainer fieldsetContainer in fieldset.Containers)
                        {
                            foreach (Field field in fieldsetContainer.Fields)
                            {
                                field.Caption += " (updated)";
                            }
                        }
                    }
                }
            }
        }
    }

When a form or folder is moved there is no specific service event. However, information available in the State dictionary on the notification object can be used to determine whether the item was moved. If so, it can show where it was moved from:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<FormSavingNotification, FormSavingNotificationHandler>();
        }
    }

    public class FormSavingNotificationHandler : INotificationHandler<FormSavingNotification>
    {
        private readonly ILogger<FormSavingNotification> _logger;

        public FormSavingNotificationHandler(ILogger<FormSavingNotification> logger) => _logger = logger;

        public void Handle(FormSavingNotification notification)
        {
            foreach (Form savedEntity in notification.SavedEntities)
            {
                _logger.LogInformation($"Form updated. New parent: {savedEntity.FolderId}. Old parent: {notification.State["MovedFromFolderId"]}");
            }
        }
    }

If a folder is being moved, the key within the State dictionary is "MovedFromParentId".

Backoffice entry rendering events

When an entry for a form is rendered in the backoffice, an event is available to allow modification of the record detail. This event is available before the record details are presented to the user. This is shown in the following example:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<EntrySearchResultFetchingNotification, EntrySearchResultFetchingNotificationHandler>();
        }
    }

    public class EntrySearchResultFetchingNotificationHandler : INotificationHandler<EntrySearchResultFetchingNotification>
    {
        public void Handle(EntrySearchResultFetchingNotification notification)
        {
            var transformedFields = new List<object>();
            foreach (var field in notification.EntrySearchResult.Fields)
            {
                if (field?.ToString() == "Test")
                {
                    transformedFields.Add("Test (updated)");
                }
                else
                {
                    transformedFields.Add(field);
                }
            }

            notification.EntrySearchResult.Fields = transformedFields;
        }
    }

/*
 Applies recommended primary keys, foreign keys and indexes to Umbraco Forms tables relating to "forms in the database" (i.e.
 when configuration key StoreUmbracoFormsInDb = true).
 This replicates for SQL Server the migration AddFormKeysAndIndexes.
 */

-- Adds unique constraint to UFForms.
ALTER TABLE dbo.UFForms
ADD CONSTRAINT UK_UFForms_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFDataSource.
ALTER TABLE dbo.UFDataSource
ADD CONSTRAINT UK_UFDataSource_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFPrevalueSource.
ALTER TABLE dbo.UFPrevalueSource
ADD CONSTRAINT UK_UFPrevalueSource_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFWorkflows.
ALTER TABLE dbo.UFWorkflows
ADD CONSTRAINT UK_UFWorkflows_Key UNIQUE NONCLUSTERED 
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds index on join field in UFWorkflows.
CREATE NONCLUSTERED INDEX IX_UFWorkflows_FormId ON dbo.UFWorkflows
(
	FormId ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

Reverting the application of keys and indexes

/*
 Reverts application of recommended primary keys, foreign keys and indexes to Umbraco Forms tables relating to "forms in the database" (i.e.
 when configuration key StoreUmbracoFormsInDb = true).
 This reverts for SQL Server the migration AddFormKeysAndIndexes and can be used for rolling that back in testing.
 */

-- Reverts addition of unique constraint to UFForms.
ALTER TABLE dbo.UFForms
DROP CONSTRAINT IF EXISTS UK_UFForms_Key
GO

-- Reverts addition of unique constraint to UFPrevalueSource.
ALTER TABLE dbo.UFDataSource
DROP CONSTRAINT IF EXISTS UK_UFDataSource_Key
GO

-- Reverts addition of unique constraint to UFPrevalueSource.
ALTER TABLE dbo.UFPrevalueSource
DROP CONSTRAINT IF EXISTS UK_UFPrevalueSource_Key
GO

-- Reverts addition of unique constraint to UFWorkflows.
ALTER TABLE dbo.UFWorkflows
DROP CONSTRAINT IF EXISTS UK_UFWorkflows_Key
GO

-- Reverts addition of index on foreign key fields in UFWorkflows.
DROP INDEX IF EXISTS IX_UFWorkflows_FormId ON dbo.UFWorkflows
GO

-- Reverts addition of index on foreign key fields in UFWorkflows.
DROP INDEX IF EXISTS IX_UFWorkflows_FormId ON dbo.UFWorkflows
GO

In Umbraco Forms, reCAPTCHA V2 comes out of the box to help you to protect your site from spam, malicious people, and so on.

Enabling reCAPTCHA V2

Follow these steps to enable reCAPTCHA V2 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v2 enabled.

3. Add a new question and select ReCAPTCHA v2 as its answer type.

4. Make sure the field is set as Mandatory.

5. Configure ReCAPTCHA settings in the appSettings.json file to include public and private keys:

"Umbraco"{
    "Forms": {
      "FieldTypes": {
        "Recaptcha2": {
            "PublicKey": "",
            "PrivateKey": ""
          }
        }
      }
   }

You can create your keys by logging into your reCAPTCHA account.

To add a new type, no matter if it's a workflow, field, data source, etc, there is a number of tasks to perform to connect to the Forms provider model. This chapter walks through each step and describes how each part works. This chapter will reference the creation of a workflow type. It is, however, the same process for all types.

Preparations

Create a new class library project in Visual Studio add references to the Umbraco.Forms.Core.dll (available via referencing the NuGet package). You might also need to reference Umbraco.Forms.Core.Providers.

Adding the type to Forms

The Forms API contains a collection of classes that can be registered at startup or in an Umbraco component. So to add a new type to Forms you inherit from the right class. In the sample below we use the class for the workflow type.

public class LogWorkflow : Umbraco.Forms.Core.WorkflowType
{
    private readonly ILogger<LogWorkflow> _logger;

    public LogWorkflow(ILogger<LogWorkflow> logger)
    {
        _logger = logger;
    }

    public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context)
    {
        throw new NotImplementedException();
    }

    public override List<Exception> ValidateSettings() {
        throw new NotImplementedException();
    }
}

When you implement this class you get two methods added. One of them is Execute which performs the execution of the workflow and the other is a method which validates the workflow settings, we will get back to these settings later on.

Any dependencies required that are registered with the dependency injection container can be provided via the constructor.

Even though we have the class inheritance in place, we still need to add a bit of default information.

Setting up basic type information

Even though we have the class inheritance in place, we still need to add a bit of default information. This information is added in the class's constructor like this:

public LogWorkflow(ILogger<LogWorkflow> logger) {

    _logger = logger;

    this.Name = "The logging workflow";
    this.Id = new Guid("D6A2C406-CF89-11DE-B075-55B055D89593");
    this.Description = "This will save an entry to the log";
}

All three are mandatory and the ID must be unique, otherwise the type might conflict with an existing one.

Adding settings to a type

Now that we have a basic class setup, we would like to pass setting items to the type. So we can reuse the type on multiple items but with different settings. To add a setting to a type, we add a property to the class, and give it a specific attribute like this:

[Umbraco.Forms.Core.Attributes.Setting("Log Header",
        Description = "Log item header",
        View = "TextField")]
public string LogHeader { get; set; }

The Umbraco.Forms.Core.Attributes.Setting registers the property in Umbraco Forms and there will automatically be UI and storage generated for it. In the attribute, a name, description and the view to be rendered is defined.

With the attribute in place, the property value is set every time the class is instantiated by Umbraco Forms. This means you can use the property in your code like this:

[Umbraco.Forms.Core.Attributes.Setting("Document ID",
        Description = "Node the log entry belongs to",
        View = "Pickers.Content")]
public string Document { get; set; }

public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context) {
    _logger.LogInformation("Record submitted from: {IP}", context.Record.IP);
    return WorkflowExecutionStatus.Completed;
}

For all types that use the provider model, settings work this way. By adding the Setting attribute Forms automatically registers the property in the UI and sets the value when the class is instantiated.

Validate type settings with ValidateSettings()

The ValidateSettings() method which can be found on all types supporting dynamic settings, is used for making sure the data entered by the user is valid and works with the type.

public override List<Exception> ValidateSettings() {
    List<Exception> exceptions = new List<Exception>();
    int docId = 0;
    if (!int.TryParse(Document, out docId))
        exceptions.Add(new Exception("Document is not a valid integer"));
    return exceptions;
}

Registering the class with Umbraco and Forms

To register the type, ensure your web application project has a reference to the class library - either via a project or NuGet reference - and add the following code into the startup pipeline. In this example, the registration is implemented as an extension method to IUmbracoBuilder and should be called from Startup.cs:

public static IUmbracoBuilder AddUmbracoFormsCustomProviders(this IUmbracoBuilder builder)
{
    builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
        .Add<LogWorkflow>();
}

An alternative approach is to use a composer, as per this example:

public class UmbracoFormsCustomProvidersComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
            .Add<LogWorkflow>();
    }
}

From Umbraco Forms 9.5 and 10.0, there are further convenience methods you can use for registering custom types. These are found in the namespace Umbraco.Forms.Core.Providers.Extensions.

For example, instead of the following:

    builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
        .Add<LogWorkflow>();

Your workflow can be registered using:

    builder.AddFormsWorkflow<LogWorkflow>():

Or:

    builder.FormsWorkflows().Add<LogWorkflow>();

Existing items that are not required in a particular installation can be removed with:

    builder.FormsWorkflows().Exclude<Slack>();

Also look in the reference chapter for complete class implementations of workflows, fields and export types.

Overriding default providers in Umbraco Forms

It is possible to override and inherit the original provider, be it a Field Type or Workflow etc. The only requirement when inheriting a fieldtype that you wish to override is to ensure you do not override/change the Id set for the provider, and make sure your class is public.

Here is an example of overriding the Textarea field aka Long Answer.

public class TextareaWithCount : Umbraco.Forms.Core.Providers.FieldTypes.Textarea
{
    // Added a new setting when we add our field to the form
    [Umbraco.Forms.Core.Attributes.Setting("Max length",
    Description = "Max length",
    View = "TextField")]
    public string MaxNumberOfChars { get; set; }

    public TextareaWithCount()
    {
        // Set a different view for this fieldtype
        this.FieldTypeViewName = "FieldType.TextareaWithCount.cshtml";

        // We can change the default name of 'Long answer' to something that suits us
        this.Name = "Long Answer with Limit";
    }

    public override IEnumerable<string> ValidateField(Form form, Field field, IEnumerable<object> postedValues, HttpContext context, IPlaceholderParsingService placeholderParsingService, List<string> errors)
    {
        var baseValidation = base.ValidateField(form, field, postedValues, context, placeholderParsingService, errors);
        var value = postedValues.FirstOrDefault();

        if (value != null && value.ToString().Length < int.Parse(MaxNumberOfChars))
        {
            return baseValidation;
        }

        var custom = new List<string>();
        custom.AddRange(baseValidation);
        custom.Add("String is way way way too long!");

        return custom;
    }
}

As discussed in the previous section, you must also register the extended field type within a composer. You also need to create the the backoffice field type view.

Composer:

public class UmbracoFormsCustomProvidersComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.FormsFields().Add<TextareaWithCount>();
    }
}

Backoffice View:

Add a new HTML file as per the name of the field class (e.g. textareawithcount.html) to \wwwroot\App_Plugins\umbracoforms\Backoffice\Common\FieldTypes\ within your project. For this example, we can copy the original textarea.html file used by the standard 'Long Answer' field.

The AngularJS client-side files are shipped with Umbraco Forms as part of a Razor Class Library. So you won't find these files on disk when you install the package.

However if you do want to reference them you can view and extract them from the Umbraco.Forms.StaticAssets NuGet package.

Umbraco Forms has some magic strings that enable you to render values from various sources, such as session, cookies and Umbraco page fields.

Where can I use magic strings?

Magic strings can be used in form fields as a label, description or default value. As an example they can be used in default values in hidden fields - normally in the form of referral codes from a session, cookie or request item.

These values can also be used for properties and settings in workflows. This means you can use name and email fields from a form to create a personal 'Thank you' email.

Sources of magic string values

Request

[@SomeRequestItem] this allows you to display an item from the current HttpContext.Request with the key of 'SomeRequestItem'.

Some examples of variables that are normally available in HttpContext.Request:

• [@Url]: Insert the current URL

• [@Http_Referer]: The previous visited URL (if available)

• [@Remote_Addr]: The IP address of the visitor (stored by default by Umbraco)

• [@Http_User_Agent]: The browser of the visitor

The variables are not case-sensitive.

You can use it for any available query string variable in the URL as well. If your URL has the query string [email protected], you can get the value of the query string into your field by using [@email].

Dictionary Items

For multi-lingual websites, rather than hard-coding labels like form field captions, a dictionary key can be entered as, for example, #MyKey. When the form is rendered, the placeholder will be replaced by the value of the dictionary item identified by the key, according to the current language.

In most cases, the field must contain only the magic string for the replacement to be carried out. This makes sense for translated values, as you will want the whole phrase replaced when, for example, using one for a field's placeholder.

We also translate dictionary keys found within the rich text field, which will be contained within HTML tags. Here we look for dictionary keys making up the full inner text of a tag. So for example, <p>#myKey</p> would be translated, but <p>Lorem ipsum #myKey dolor sit amet.</p> would not.

Session & Cookies

[%SomeSessionOrCookieItem] this allows you to display an item from the current HttpContext.Session with the key of 'SomeSessionOrCookieItem'. The session key can only contain alphanumeric chars and you cannot use dots for example. [%Member.Firstname] cannot be used, but [%MemberFirstname] can be used. You would have to fill these session keys yourself.

If the item cannot be found in the collection of session keys, it will then try to find the item from the HttpContext.Cookies collection with the same key.

Umbraco Page field

[#myUmbracoField] this allows you to insert a property of that page and is based on the alias of the field. If your page has a property with the alias 'title', you can use [#title] in your form.

Some extra variables are:

• [#pageName]: The nodename of the current page

• [#pageID]: The node ID of the current page

Recursive Umbraco Page field

[$myRecursiveItem] this allows you to parse the Umbraco Document Type property myRecursiveItem. So if the current page does not contain a value for this then it will request it from the parent up until the root or until it finds a value.

Umbraco Form field

{myAliasForFormField} this allows you to display the entered value for that specific field from the form submission. Used in workflows to send an automated email back to the customer based on the email address submitted in the form. The value here needs to be the alias of the field, and not the name of the field.

Some extra variables are:

• {record.id}: The ID of the current record - this is only accessible on workflows triggered "on approve" rather than "on submit"

• {record.updated}: The updated date/time of the current record

• {record.created}: The created date/time of the current record

• {record.umbracopageid}: The Umbraco Page ID the form was submitted on

• {record.uniqueid}: The unique ID of the current record

• {record.ip}: The IP address that was used when the form was submitted

• {record.memberkey}: The member key that was used when the form was submitted

Member properties from a form submission

{member.FOO} with the prefix of member, the same syntax will allow you to retrieve information about the submission if it was submitted by a logged-in member.

Formatting magic strings

Using a magic string such as in the examples above will output the values exactly as read from the source. From Forms 10.2, it's possible to apply a format string to customize the output.

The syntax follows that of AngularJS filters, i.e. [<magic-string> | <formatFunction>: <arg1>: <arg2>].

For example, to truncate a string value read from an Umbraco page field with alias title, you would use:

[#title | truncate: 10]

Umbraco Forms ships with the following filters:

The format strings used for formatting dates and numbers are the standard or custom .NET date and numeric format strings respectively.

Further magic string format functions can be created in code for use in forms.

How can I parse these values elsewhere in my C# code or Razor Views?

A service implemented by the IPlaceholderParsingService interface is available for use in custom code or views. It's found in the Umbraco.Forms.Core.Services namespace.

In a controller you can inject it via the constructor and it can also be injected into views via:

@using Umbraco.Forms.Core.Services;
@inject IPlaceholderParsingService PlaceholderParsingService

The interface implements a single method, ParsePlaceHolders, that can be used for parsing magic strings. There are a few overloads available for use depending on the context.

If parameters for the Record or Form are omitted, magic strings relating to these objects will be removed.

There is also a public extension method ParsePlaceHolders() extending the string object in the Umbraco.Forms.Core.Extensions namespace, again available with some overloads allowing the provision of a Form or Record object if available.

In Umbraco Forms, it is only possible to store Form data in the database.

If you are upgrading to Umbraco 9 or later and using Forms, you should first migrate the Forms to the database using Forms 8. As of Umbraco Forms version 8.5.0 it is possible to persist all Forms data in the Umbraco database. This includes definitions for each Form and their fields, as well as workflow definitions and prevalues.

Enable storing Forms definitions in the database

To persist Umbraco Forms definitions in the database, follow these steps:

1. Upgrade to at least Umbraco Forms version 8.5.2.

2. Open the configuration file App_Plugins\UmbracoForms\UmbracoForms.config.

3. Locate the StoreUmbracoFormsInDb key in the <settings> section, and make sure it has the following value:

   Copy

   <setting key="StoreUmbracoFormsInDb" value="True" />

4. Save the file.

If you are working with a Umbraco Cloud project, make sure you follow the migration steps outlined in the Umbraco Forms on Cloud article.

When you save the file, the site will restart and run a migration step, migrating the files to the Umbraco database.

Migrating Forms in files into a site

You can force Forms to rerun the migration of the file-format Forms if you have a Umbraco 8 site storing Forms in the database.

First of all, you should ensure that you have enabled the setting that persists Forms in the database, as the migration requires this (StoreUmbracoFormsInDb) key. We highly recommend testing this on a local setup before applying it to your live site.

1. Copy over the Forms, workflows, prevaluesources, and datasource files to the site into ~\App_Data\UmbracoForms\Data.

2. Go to the database and find the [umbracoKeyValue] table.

3. Find the Form's row and check that the value is 1d084819-84ba-4ac7-b152-2c3d167d22bc (if not you are not currently working with Forms in the database, changing the setting should be enough).

4. Change that value to {forms-init-complete}.

5. Restart the site.

The site will now try to migrate the Forms files into the database. In the umbracoTraceLog, you can follow the progress. It will throw errors if anything goes wrong. Additionally, it will log out "The Umbraco Forms DB table {TableName} already exists" for the 4 Forms tables before starting the migration.

The labels, descriptions, and buttons that make up the backoffice screens for Umbraco Forms can be translated into different languages.

When an editor chooses a language for their account, Umbraco CMS will render appropriate translations. The translations will contain a file for that language and a key for the label in question. If either of these can't be found, the label will be displayed in English (US).

Language Files

Umbraco Forms ships with translations for the following languages:

• Czech (cs-cz.xml)

• Danish (da-dk.xml)

• Spanish (es-es.xml)

• French (fr-fr.xml)

• Italian (it-it.xml)

• Polish (pl-pl.xml)

• UK English (en-gb.xml)

• US English (en-us.xml)

If the language you require does not exist, it's possible to create your own by duplicating the default en-us.xml file. You can then save it with the appropriate culture code for the language you need and replace the English text with the translated version.

As of Forms 10, the file no longer exists on disk and is shipped as part of the Umbraco.Forms.StaticAssets NuGet package. You can open this package, either locally using Nuget Package Explorer, or online by clicking the "Open in NuGet Package Explorer" link. You'll find the file at staticwebassets/Lang/en-us.xml.

Once translated, the new file should be saved into the App_Plugins/UmbracoForms/app/lang/ folder.

This builds on the "adding a type to the provider model" chapter and applies to Umbraco Forms version 4.4.1 and higher

Add a new class to your project and have it inherit from Umbraco.Forms.Core.ExportType and you have two options when implementing the class.

Basic Example

When implementing the method public override string ExportRecords(RecordExportFilter filter) in your export provider class. You need to return the final string you wish to write to a file. Such as .txt file or .csv and you can perform your logic to build up a comma separated string for a CSV file in the ExportRecords method.

The FileExtension property is the file extension such as zip, txt or csv of the file you will be generating & serving from the file system as the export file.

In this example below we will create a single HTML file which takes all the submissions/entries to be displayed as a HTML report. We will do this in conjunction with a Razor partial view to help build up our HTML and thus merge it with the form submission data to generate a string of HTML.

Provider Class

using System;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Searchers;
using Umbraco.Forms.Web.Helpers;

namespace MyFormsExtensions
{
    public class ExportToHtmlReport : ExportType
    {
        private readonly IFormRecordSearcher _formRecordSearcher;

        public ExportToHtmlReport(
            IHostingEnvironment hostingEnvironment,
            IFormRecordSearcher formRecordSearcher)
            : base(hostingEnvironment)
        {
            _formRecordSearcher = formRecordSearcher;

            this.Name = "Export as HTML";
            this.Description = "Export entries as a single HTML report";
            this.Id = new Guid("4117D352-FB41-4A4C-96F5-F6EF35B384D2");
            this.FileExtension = "html";
            this.Icon = "icon-article";        }

        public override string ExportRecords(RecordExportFilter filter)
        {
            var view = "~/Views/Partials/Forms/Export/html-report.cshtml";
            EntrySearchResultCollection model = _formRecordSearcher.QueryDataBase(filter);
            return ViewHelper.RenderPartialViewToString(view, model);
        }
    }
}

Razor Partial View

@model Umbraco.Forms.Web.Models.Backoffice.EntrySearchResultCollection

@{
    var submissions = Model.Results.ToList();
    var schemaItems = Model.schema.ToList();
}

<h1>Form Submissions</h1>

@foreach (var submission in submissions)
{
    var values = submission.Fields.ToList();

    for (int i = 0; i < schemaItems.Count; i++)
    {
        <strong>@schemaItems[i].Name</strong> @values[i] <br />
    }

    <hr/>
}

Advanced Example

This approach gives us more flexibility in creating the file we wish to serve as the exported file. We do this for the export to Excel file export provider we ship in Umbraco Forms. With this we can use a library to create the Excel file and store it in a temporary location before we send back the filepath for the browser to stream down the export file.

In this example we will create a collection of text files, one for each submission which is then zipped up into a single file and served as the export file.

using System;
using System.IO;
using System.IO.Compression;
using System.Linq;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Searchers;

namespace MyFormsExtensions
{
    public class ExportToTextFiles : ExportType
    {
        private readonly IFormRecordSearcher _formRecordSearcher;

        public ExportToTextFiles(
            IHostingEnvironment hostingEnvironment,
            IFormRecordSearcher formRecordSearcher)
            : base(hostingEnvironment)
        {
            _formRecordSearcher = formRecordSearcher;

            this.Name = "Export as text files";
            this.Description = "Export entries as text files inside a zip file";
            this.Id = new Guid("171CABC9-2207-4575-83D5-2A77E824D5DB");
            this.FileExtension = "zip";
            this.Icon = "icon-zip";
        }

        /// <summary>
        /// We do not implement this method from the interface
        /// As this method is called from ExportToFile that we also override here & is expecting the file contents as a string to be written as a stream to a file
        /// Which would be OK if we were creating a CSV or a single based file that can have a simple string written as a string such as one large HTML report or XML file perhaps
        /// </summary>
        public override string ExportRecords(RecordExportFilter filter) => throw new NotImplementedException();

        /// <summary>
        /// This gives us greater control of the export process
        /// </summary>
        /// <param name="filter">
        /// This filter contains the date range & other search parameters to limit the entries we are exporting
        /// </param>
        /// <param name="filepath">
        /// The filepath that the export file is expecting to be served from
        /// So ensure that the zip of text files is saved at this location
        /// </param>
        /// <returns>The final file path to serve up as the export - this is unlikely to change through the export logic</returns>
        public override string ExportToFile(RecordExportFilter filter, string filepath)
        {
            // Before Save - Check Path, Directory & Previous File export does not exist
            string pathToSaveZipFile = filepath;

            // Check our path does not contain \\
            // If not, use the filePath
            if (filepath.Contains('\\') == false)
            {
                pathToSaveZipFile = HostingEnvironment.MapPathContentRoot(filepath);
            }

            // Get the directory (strip out \\ if it exists)
            var dir = filepath.Substring(0, filepath.LastIndexOf('\\'));
            var tempFileDir = Path.Combine(dir, "text-files");


            // If the path does not end with our file extension, ensure it's added
            if (pathToSaveZipFile.EndsWith("." + FileExtension) == false)
            {
                pathToSaveZipFile += "." + FileExtension;
            }

            // Check that the directory where we will save the ZIP file temporarily exists
            // If not just create it
            if (Directory.Exists(tempFileDir) == false)
            {
                Directory.CreateDirectory(tempFileDir);
            }

            // Check if the zip file exists already - if so delete it, as we have a new update
            if (File.Exists(pathToSaveZipFile))
            {
                File.Delete(pathToSaveZipFile);
            }

            // Query the DB for submissions to export based on the filter
            EntrySearchResultCollection submissions = _formRecordSearcher.QueryDataBase(filter);

            // Get the schema objects to a list so we can get items using position index
            var schemaItems = submissions.schema.ToList();

            // We will use this to store our contents of our file to save as a text file
            var fileContents = string.Empty;

            // For each submission we have build up a string to save to a text file
            foreach (EntrySearchResult submission in submissions.Results)
            {
                // The submitted data for the form submission
                var submissionData = submission.Fields.ToList();

                // For loop to match the schema position to the submission data
                for (int i = 0; i < schemaItems.Count; i++)
                {
                    // Concat a string of the name of the field & its stored data
                    fileContents += schemaItems[i].Name + ": " + submissionData[i] + Environment.NewLine;
                }

                // Now save the contents to a text file
                // Base it on the format of the record submission unique id
                var textFileName = Path.Combine(tempFileDir, submission.UniqueId + ".txt");
                File.WriteAllText(textFileName, fileContents);

                // Reset fileContents to be empty again
                fileContents = string.Empty;
            }

            // Now we have a temp folder full of text files
            // Generate a zip file containing them & save that
            ZipFile.CreateFromDirectory(tempFileDir, pathToSaveZipFile);

            // Tidy up after ourselves & delete the temp folder of text files
            if (Directory.Exists(tempFileDir))
            {
                Directory.Delete(tempFileDir, true);
            }

            // Return the path where we saved the zip file containing the text files
            return pathToSaveZipFile;
        }
    }
}

/*
 Applies recommended primary keys, foreign keys and indexes to core Umbraco Forms tables.
 This replicates for SQL Server the migration AddRecordKeysAndIndexes.
 */

-- Adds relationship between UFRecords and UFRecordFields.
ALTER TABLE dbo.UFRecordFields
ADD CONSTRAINT
	FK_UFRecordFields_UFRecords_Record FOREIGN KEY
	(
	Record
	) REFERENCES dbo.UFRecords
	(
	Id
	) ON UPDATE  NO ACTION 
	 ON DELETE  NO ACTION 
GO

-- Adds primary keys to UFRecordData* tables.
ALTER TABLE dbo.UFRecordDataBit
ADD CONSTRAINT
	PK_UFRecordDataBit PRIMARY KEY CLUSTERED 
	(
	Id
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

ALTER TABLE dbo.UFRecordDataDateTime
ADD CONSTRAINT
	PK_UFRecordDataDateTime PRIMARY KEY CLUSTERED 
	(
	Id
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

ALTER TABLE dbo.UFRecordDataInteger
ADD CONSTRAINT
	PK_UFRecordDataInteger PRIMARY KEY CLUSTERED 
	(
	Id
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

ALTER TABLE dbo.UFRecordDataLongString
ADD CONSTRAINT
	PK_UFRecordDataLongString PRIMARY KEY CLUSTERED 
	(
	Id
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds relationship between UFRecordFields and UFREcordData* tables.
ALTER TABLE dbo.UFRecordDataBit
ADD CONSTRAINT
	FK_UFRecordDataBit_UFRecordFields_Key FOREIGN KEY
	(
	[Key]
	) REFERENCES dbo.UFRecordFields
	(
	[Key]
	) ON UPDATE  NO ACTION 
	 ON DELETE  NO ACTION 
GO

ALTER TABLE dbo.UFRecordDataDateTime
ADD CONSTRAINT
	FK_UFRecordDataDateTime_UFRecordFields_Key FOREIGN KEY
	(
	[Key]
	) REFERENCES dbo.UFRecordFields
	(
	[Key]
	) ON UPDATE  NO ACTION 
	 ON DELETE  NO ACTION 
GO

ALTER TABLE dbo.UFRecordDataInteger
ADD CONSTRAINT
	FK_UFRecordDataInteger_UFRecordFields_Key FOREIGN KEY
	(
	[Key]
	) REFERENCES dbo.UFRecordFields
	(
	[Key]
	) ON UPDATE  NO ACTION 
	 ON DELETE  NO ACTION 
GO

ALTER TABLE dbo.UFRecordDataLongString
ADD CONSTRAINT
	FK_UFRecordDataLongString_UFRecordFields_Key FOREIGN KEY
	(
	[Key]
	) REFERENCES dbo.UFRecordFields
	(
	[Key]
	) ON UPDATE  NO ACTION 
	 ON DELETE  NO ACTION 
GO

-- Adds index on foreign key fields in UFREcordData* tables.
CREATE NONCLUSTERED INDEX IX_UFRecordDataBit_Key ON dbo.UFRecordDataBit
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

CREATE NONCLUSTERED INDEX IX_UFRecordDataDateTime_Key ON dbo.UFRecordDataDateTime
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

CREATE NONCLUSTERED INDEX IX_UFRecordDataInteger_Key ON dbo.UFRecordDataInteger
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

CREATE NONCLUSTERED INDEX IX_UFRecordDataLongString_Key ON dbo.UFRecordDataLongString
(
	[Key] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds primary key to UFUserSecurity.
ALTER TABLE dbo.UFUserSecurity
ADD CONSTRAINT
	PK_UFUserSecurity PRIMARY KEY CLUSTERED 
	(
	[User]
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds primary key to UFUserFormSecurity.
ALTER TABLE dbo.UFUserFormSecurity
ADD CONSTRAINT
	PK_UFUserFormSecurity PRIMARY KEY CLUSTERED 
	(
	Id
	) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

-- Adds unique constraint to UFUserFormSecurity across user/form fields.
ALTER TABLE dbo.UFUserFormSecurity
ADD CONSTRAINT UK_UFUserFormSecurity_User_Form UNIQUE NONCLUSTERED 
(
	[User] ASC,
	[Form] ASC
) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

Revert application of keys and indexes

/*
 Reverts application of recommended primary keys, foreign keys and indexes to core Umbraco Forms tables.
 This reverts for SQL Server the migration AddRecordKeysAndIndexes and can be used for rolling that back in testing.
 */

-- Reverts addition of relationship between UFRecords and UFRecordFields.
ALTER TABLE dbo.UFRecordFields
DROP CONSTRAINT IF EXISTS FK_UFRecordFields_UFRecords_Record
GO

-- Reverts addition of primary keys to UFRecordData* tables.
ALTER TABLE dbo.UFRecordDataBit
DROP CONSTRAINT IF EXISTS PK_UFRecordDataBit
GO

ALTER TABLE dbo.UFRecordDataDateTime
DROP CONSTRAINT IF EXISTS PK_UFRecordDataDateTime
GO

ALTER TABLE dbo.UFRecordDataInteger
DROP CONSTRAINT IF EXISTS PK_UFRecordDataInteger
GO

ALTER TABLE dbo.UFRecordDataLongString
DROP CONSTRAINT IF EXISTS PK_UFRecordDataLongString
GO

-- Reverts addition of relationship between UFRecordFields and UFREcordData* tables.
ALTER TABLE dbo.UFRecordDataBit
DROP CONSTRAINT IF EXISTS FK_UFRecordDataBit_UFRecordFields_Key
GO

ALTER TABLE dbo.UFRecordDataDateTime
DROP CONSTRAINT IF EXISTS FK_UFRecordDataDateTime_UFRecordFields_Key
GO

ALTER TABLE dbo.UFRecordDataInteger
DROP CONSTRAINT IF EXISTS FK_UFRecordDataInteger_UFRecordFields_Key
GO

ALTER TABLE dbo.UFRecordDataLongString
DROP CONSTRAINT IF EXISTS FK_UFRecordDataLongString_UFRecordFields_Key
GO

-- Reverts addition of index on foreign key fields in UFREcordData* tables.
DROP INDEX IF EXISTS IX_UFRecordDataBit_Key ON dbo.UFRecordDataBit
GO

DROP INDEX IF EXISTS IX_UFRecordDataDateTime_Key ON dbo.UFRecordDataDateTime
GO

DROP INDEX IF EXISTS IX_UFRecordDataInteger_Key ON dbo.UFRecordDataInteger
GO

DROP INDEX IF EXISTS IX_UFRecordDataLongString_Key ON dbo.UFRecordDataLongString
GO

-- Reverts addition of primary key to UFUserSecurity
ALTER TABLE dbo.UFUserSecurity
DROP CONSTRAINT IF EXISTS PK_UFUserSecurity
GO

-- Reverts addition of primary key to UFUserFormSecurity
ALTER TABLE dbo.UFUserFormSecurity
DROP CONSTRAINT IF EXISTS PK_UFUserFormSecurity
GO

-- Reverts addition of unique constraint to UFUserFormSecurity across user/form fields.
ALTER TABLE dbo.UFUserFormSecurity
DROP CONSTRAINT IF EXISTS UK_UFUserFormSecurity_User_Form
GO

By default, a single workflow is added when a new form is created. This workflow will send a copy of the form to the email address of the current backoffice user.

A single "data consent" field will also be added unless it has been disabled via configuration.

It's possible to amend this behavior and change it to fit your needs.

Implementing a Custom Behavior

Two interfaces are used to abstract the logic for setting default fields and workflows for a form. They are IApplyDefaultFieldsBehavior and IApplyDefaultWorkflowsBehavior respectively.

The default behaviors are defined using built-in, internal classes that implement this interface.

You can create your own implementation of these interfaces.

Example - Providing a Custom Apply Workflows Behavior

An illustrative example, adding a custom workflow that writes to the log, is shown below.

Firstly, the custom workflow:

Secondly, the custom implementation of IApplyDefaultWorkflowsBehavior:

Finally, to register the custom implementation in place of the default one:

Setting a Mandatory Default Workflow

When adding a default workflow in code, it's possible to make it mandatory, which will prevent editors from removing it from a form.

You can see this in the example above, where the IsMandatory property of the created FormWorkflowWithTypeSettings instance is set to true.

Example - Providing a Custom Apply Fields Behavior

The following class shows the default implementation provided with Forms. You can copy this and customize it to your needs.

Again, you will need to register your custom class, for example, in a composer with:

There are multiple built-in workflow types that can be used to extend the functionality of your Form.

• Change Record State

• Post as XML

• Save as an XML file

• Save as Umbraco Content Node

• Send Email

• Send Email with Template (Razor)

• Send Form to URL

• Send XSLT Transformed Email

• Slack