Install the Drupal CMS Remediation Helpers Module

Summary

The Siteimprove CMS Remediation Helpers module gives the CMS Remediation Agent additional information for locating Drupal content and identifying associated routes and Twig templates. It is recommended for Drupal connections, particularly when pages use more complex content structures.

The helper is optional for supported page content that the agent can locate through Drupal’s standard APIs. It supplies inspection information; it does not make every content structure editable or automatically change theme and template code.

Before you begin

Test the installation in a non-production environment first and include the module and dependency in your normal deployment process. The ZIP contains the custom module source; it does not include Drupal or Decoupled Router.

Download the helper

Download siteimprove_cms_remediation_helpers-85f1400.zip located at the bottom of this article. The archive contains the siteimprove_cms_remediation_helpers directory. Keep that directory name when installing it.

Install the dependency and module

1. From the Drupal project root, install Decoupled Router with Composer: composer require 'drupal/decoupled_router:^2.0'
2. Extract the helper directory into modules/custom inside the Drupal web root. For a project whose web root is web, the resulting module directory is: web/modules/custom/siteimprove_cms_remediation_helpers
3. In Drupal Extend, enable JSON: API, HTTP Basic Authentication, Decoupled Router, and Siteimprove CMS Remediation Helpers.
4. Rebuild Drupal caches after enabling the modules.

Extracting the ZIP does not install its dependencies. Avoid an extra nested directory: the module’s .info.yml file must sit directly inside siteimprove_cms_remediation_helpers.

Configure the service account

1. In Drupal, open People > Permissions and find the dedicated service-account role.
2. Grant Inspect routes. This allows the helper to provide route and content-location information.
3. Grant Inspect Twig templates via API. This allows inspection of template paths and source, and enables template markers for the permitted account.
4. Keep the content and moderation permissions required to update the intended content. The helper’s inspection permissions do not grant content-editing access.
5. Save the permissions and confirm that the dedicated account has the role.

Assign these inspection permissions only to the trusted service-account role. Do not grant them to Anonymous user or the general Authenticated user role, because they expose route information and template source.

Basic Auth behaviour

This helper version makes Drupal’s Basic Auth provider available across site requests. Requests authenticated with Basic Auth must have the Inspect Twig templates via API permission. Your administrator should review other integrations using Basic Auth before enabling the helper.

Verify the connection

1. In Siteimprove, go to Settings > AI management and find the site under Site access and CMS connections.
2. Confirm that the Drupal connection uses the correct HTTPS site root and the dedicated account’s credentials.
3. Use a Siteimprove role that allows Use CMS Remediation and has access to AI Remediate.
4. Open a supported accessibility issue in Page Report, generate a suggested fix, and select Analyze in CMS.
5. Review the current content, proposed replacement, and destination. Cancel the proposal if you are testing discovery only.

If you choose to apply a test change, check the stored content and publication status in Drupal, then re-check the rendered page in Siteimprove. The helper does not guarantee a new revision or a particular publication outcome for every content type.

Troubleshooting

The helper is not listed in Extend

Check that the helper directory is inside the Drupal web root’s modules/custom directory and that there is no additional nested folder. Confirm that the package is compatible with your Drupal release, then rebuild caches.

Drupal reports a missing dependency

Confirm that Composer installed Decoupled Router and that JSON:API and HTTP Basic Authentication are enabled. Downloading or extracting the helper ZIP alone does not install the required dependency.

The connection returns 401 or 403

Confirm the saved username and password, the account’s status, and whether Basic Auth reaches Drupal. Check that the service-account role has both helper permissions and the content permissions required for the operation. Inspect Twig templates via API is required for Basic Auth requests with this helper version.

The agent still cannot locate or change content

Confirm the site root and selected page, then check the account’s access to the relevant content and fields. Theme and template code requires a developer change. Installing the helper provides additional investigation context; it does not add automatic fixes for unsupported content structures.

Related information

CMS Remediation Agent overview

Decoupled Router requirements and installation

Drupal JSON API update requirements