Return to site

The Webform module now provides Group integration for submission management

· drupal,webform,group,integrations

About the Webform module

The Webform module is a form builder and submission manager for Drupal. The Webform module allows site builders to customize forms and route submissions to multiple systems, including email, remote servers, and spreadsheets.

About the Group module

The Group module allows site builders to create arbitrary collections of content and users on a site and then grant users access to these collections. The Group module allows sites to build communities and manage their organization by creating groups of users with various levels of membership.

Problem

The Webform module for Drupal 8 does not fully integrate with the Group module. In Drupal 8, webforms are configuration entities, however, the Group module currently only supports content entities. To learn more about this issue, see Issue #2856333: Webform as group content.

Webforms can be attached to nodes, which are content entities which are supported by the Group module. This approach only provides access controls to determine which group members can simply view and submit a webform. It does not provide webform submission and element level access controls.

For example, a group could have a dedicated event registration system with a dedicated registration webform. A group administrator can control who has access to the event registration webform but there is no mechanism to allow group-specific roles to view, manage, and delete event registrations.

Solution

Provide webform submission and element level access controls to webforms attached to nodes.

Existing access controls

The Webform module already provides roles, user, and permission level access controls to webforms, submissions, and elements. There is even a dedicated Webform Access module that provides webform node-specific access controls using webform specific groups. The Webform Access module is a lightweight group-based access control system for sites that don't need a full-blown Group module implementation.

Extending access controls

The Group module includes support from group-specific roles known as 'Group roles'. 'Group roles' are similar to Drupal's out-of-box user, roles, and permissions that allow administrators to select which roles with permissions are applicable to a user. 'Group roles' are specific to members of the group. Since the Webform module already provides 'user role' access controls, it makes sense to extend this solution to support 'Group role' access controls. In other words, anywhere you can select 'user role' level access, you can now set 'Group role' level access.

'Group roles' have been added to the webform access controls and element-specific access controls.

Webform access controls

Once the Webform Group module is enabled, when you navigate to a webform's access form, you will see the 'Group (node) roles' select menu appended to every operation/permission except for configuration access. Every group type role is listed and general roles are also supported. For example, you can select the 'Member' role and all members of the current group will be automatically assigned this permission. For example, members of the current group can be allowed to edit their 'own' submissions.

The current group is determined by the currently loaded webform node's parent group relationship. Since webform submission stores the webform node as the source entity, a webform submission is also able to load the current group based on the source entity relationship. In other words, as soon as a webform node is associated with a group, the 'Group role' access controls will start being applied to the Webform node and its submissions.

Below is a screenshot of 'Group (node) roles' on the webform access form.

'Group (node) roles' on the webform access form

Element access controls

To allow groups to fully administer a webform node's submissions, it helps to provide administrative elements on a webform. Administrative elements are just webform elements with access controls. Now, you can apply 'Group role' access control and allow certain group roles to view and update administrative elements. The most common use case for administrative elements is to permit certain users/roles to add notes and reviews to a submission.

 

Below is a screenshot of 'Group roles' on the element edit form.

'Group roles' on the element edit form

Email handler tokens

Webform email handlers now also include the ability to send emails to all members of a group role. For example, an email notification can be sent to all members of a group or just a few people who are assigned the 'Manager' group role. In the backend, the email handler's group roles are defined as tokens that return a comma-delimited list of email addresses.

To allow group roles to receive emails, site builders must explicitly allow each group role to be enabled and available to receive an email. This ensures that site builders understand that all group role member's email addresses will be exposed to anyone building and configuring a webform.

Email handler tokens

Some limitations and provisos

Webform Group integration is limited to webform node submission management. The recommended workflow would be for a site builder to create a shared webform that is reused by multiple groups. Each group has a dedicated webform node instance for the shared webform. The new webform group roles access controls are then used to decide which group roles (aka members) can create, update, and delete their own submission or any submissions.

To allow a group to create one-off, group-specific webforms, site builders would have to use the existing webform permission system, possibly combined with some custom code to make it easier for a created webform to be associated with a specific group.

Webform Group Demo module

Besides telling someone how a feature or module is supposed to work, it also helps to show them how the feature or module works. The Group module is a very powerful and flexible solution that requires a site builder to understand the concept of group types, roles, members, and content. Sometimes the best way to understand a module is to build out a demo that shows the baseline functionality required to address a common or specific use case.

The Webform module now includes the Webform Group Demo module, which shows how to implement webform group role access controls for a webform referenced by multiple group-specific webform nodes. The Webform Group Demo installs configuration for two group types, which are called A and B, with some group roles including member, reviewer, manager, and administrator. An install hook creates two group instances for each group type with related user accounts, members and finally webform node instances.

Webform Group Demo module

New access control related hooks

The Webform module includes a lot of submodules, which are all optional. Packaging and maintaining these submodules makes it easier to ensure API changes do not break any integrations. A byproduct of using submodules is occasionally we’ll find the need to improve existing APIs and add new APIs or hooks.

To improve the extendability of webform access controls the below hooks were added.

Element access hook

hook_webform_element_access(

$operation,

array &$element,

\Drupal\Core\Session\AccountInterface $account = NULL

)

This hook makes it possible for modules to decide when a webform element should be visible or hidden to create, update, and view operations. It is important to note that a module can also use form and element alter hooks to set an element's #access property to FALSE to hide an element.

Submission query access alter hook

hook_webform_submission_query_access_alter(

\Drupal\Core\Database\Query\AlterableInterface $query,

array $webform_submission_tables

)

This hook allows modules to decide which submissions are visible on the results page and in a webform submission view. Altering the submission query prevents submission data from being unintentionally displayed when creating a list of submissions. Currently, only the Webform Node, Webform Access, and Webform Group implement this hook.

It is worth noting for webform and webform submission level access controls, developers should use hook_ENTITY_TYPE_access() API via hook_webform_access() and hook_webform_submsision_access().

Sponsoring a feature

The Webform Group integration was sponsored by Lutheran Church of Bavaria. The Lutheran Church of Bavaria is using Drupal 8 to build out its intranet. They are using the Groups module to build out their organization's internal subdivision workspaces, and the Webform module is being used to handle internal human resources and general requests.

If you want to sponsor a feature, please read my blog post and create a ticket in the Webform module's issue queue.

Backing the Webform module

Open Collective is providing us, Drupal, and Open Source, with a platform to experiment and improve Open Source sustainability. If you appreciate and value what you are getting from the Webform module, please consider becoming a backer of the Webform module's Open Collective.

All Posts
×

Almost done…

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

OK