Return to site

Managing Drupal and Webform configuration

· Drupal,Webform,Configuration,CMI

Webforms in Drupal 8 are configuration entities, which means that they are exportable to YAML files and this makes it easy to transfer a webform from one server environment to another. Generally, anything that defines functionality or behavior in Drupal 8 is stored as simple configuration or a configuration entity. For example, fields, views, and roles are stored as configuration entities. Things that are considered 'content' are stored in the database as content entities. Content entities include nodes, comments, taxonomy terms, users, and also webform submissions.

Configuration is exportable as YAML.
Content is stored in the database.

Managing Configuration

The core concept behind Drupal's configuration management is you can export and import how a website is configured (aka how it works) from one environment to another environment. For example, we might want to copy the configuration from your staging server to your production server. Drupal 8 has initially taken the approach that all configuration from one environment needs to be moved to the new environment. The problem is that…

The imported configuration will clobber (aka replace) any existing configuration

In the case of webforms and blocks, this is a major issue because site builders are continually updating these config entities on a production website. The Drupal community is aware of this problem - they have provided some solutions and are actively working to fix this challenge/issue in a future release of Drupal.

Improving Configuration Management

Dries Buytaert shared how we are improving Drupal's configuration management system and he notes that the currently recommended solutions are the Config Filter, Configuration Split, and Config Ignore modules.

Below is a summary of these three modules.

The Config Filter module provides an API for controlling what configuration is imported or not imported for different environments.

The Configuration Split module allows defining sets of configuration that will get exported for different environments.

The Config Ignore module allows specified configuration not to be imported (aka ignored) and overwritten.

Geert van Dort's recipe for Configuration Management

Geert van Dort has written a great resource documenting how to exclude config from configuration management in Drupal 8 and he uses Webforms as his example. Geert van Dort's article is a must-read.

There is one somewhat obvious configuration management gotcha that I have not seen fully documented.

The importing of outdated configuration gotcha

In the Webform issue queue, I am repeatedly seeing tickets related to exported webform config that have not been properly updated. For example, someone exports a Webform from 8.x-5.0-rc10, updates the Webform module to 8.x-5.0-rc26, runs the database/config updates, and then imports the Webform configuration from 8.x-5.0-rc10, which is missing any new configuration properties and changes from 8.x-5.0-rc26. Usually, I am able to pinpoint the missing update hook and suggest that someone runs the missing update hook using a drush command like…

drush php-eval 'module_load_include('install', 'webform'); webform_update_8144()';​

How to prevent the outdated configuration import gotcha

Good configuration management comes down to deciding on an approach and following it.

For me, the above concept was the most important takeaway from Michael Anello's Drupal 8 Configuration System Basics.

The solution to prevent the outdated configuration gotcha is to define a process and follow it. Below is a general outline of the steps required to make sure your exported configuration is always up-to-date

On your local or development environment:

  • Update your core and contrib modules

  • Run the database updates

  • Export your updated config

When deploying core and contrib module updates:

  • Push your core and contrib module updates to production

  • Run the database updates

  • Import your updated config

I have deliberately avoided including what specific mechanism you should be using for updating your site, which generally should be a combination of GIT, Composer, and Drush because the most important step is…

Make sure when you update Drupal core and contrib modules, your exported configuration has also been updated.

The Distribution Configuration Gotcha

Distributions are full copies of Drupal that include Drupal Core, along with additional software such as themes, modules, libraries ​and installation profiles.

Distributions include predefined configuration files, which can quickly become out-of-sync with the distribution's modules. For example, a distribution's exported configuration could be expecting an older version of the Webform module. It is the distribution maintainer's responsibility to keep the configuration up-to-date which is challenging because they have to do a full installation of the distribution, update the distribution's modules and then export the updated configuration. This is a very tedious process.

One immediate thing that a module or theme maintainer can do to help distribution maintainers is to keep change records and tag any changes that might impact a distribution. Another best practice is to try to keep configuration breaking changes to a minimum.

Webform specific configuration management tools

Exporting webform configuration

The fact that an entire Webform is exportable into one file has made it possible to create feature and element specific test webforms, which I use during automated testing. Currently, there are over 200+ test webforms included in the Webform's test modules. The Webform module provides an 'Export' tab which allows you to easily and quickly export any webform.

Webform Export Tab

If you find an issue with a webform, the best way to get help is to isolate the problem to a simple example webform, export it, and then upload it to the Webform issue queue.

Tidying exported YAML

Another minor enhancement you will see in exported Webform is that the multiline strings in the YAML file are formatted in a more readable form. To learn more, see Issue #2844452: Export configuration YAML strings as multiline. If you need your exported YAML configuration file in a slightly more readable format you can also use the Webform's tidy Drush command.

Repairing admin configuration and webform settings

If you happen upon some webform configuration that is outdated, you can run the drush webform:repair command or click the 'Repair configuration' via the admin UI under that 'Advanced' configuration tab (/admin/structure/webform/config/advanced)

Repair Webform Configuration

The future of configuration management

I have been using Drupal's configuration management since early alpha releases of Drupal 8 when configuration was not even stored in the database. The Config Filter, Configuration Split, and Config Ignore trifecta of contributed modules show how the Drupal community can work together to fix some challenging issues, paving the way for solutions to make their way in Drupal core.


The concept that we can quickly export an entire Webform into one shareable file is awesome and has made my life exponentially easier in maintaining the Webform module for Drupal 8.


The proposal for the Configuration Management 2.0 initiative is comprehensive and exciting. For example, if the Webform module could hook into the configuration import process, we should be able to repair outdated configuration as it is imported. For now, I want to say thanks to everyone involved in Drupal's Configuration Management Initiative.

All Posts

Almost done…

We just sent you an email. Please click the link in the email to confirm your subscription!