User documentation for Xanweb Data Retention.

Data Retention removes expired form submissions, optional Express uploads, database logs and old page versions. You choose each retention policy separately and review the eligible data before starting a manual cleanup.

For: Administrators · Add-on version: Data Retention 0.9.3 · Interface: Concrete CMS 9.5.7, English

On this page

• Prepare a cleanup policy
• Install the add-on
• Set retention periods for forms and logs
• Delete uploads from expired Express submissions
• Store confidential uploads privately
• Retain and delete old page versions
• Schedule automatic cleanup
• Run a cleanup manually
• Keep and read task logs
• Stop future cleanup
• Upgrade the add-on
• Uninstall the add-on
• Run commands on the server
• Resolve common problems
• Understand the scope and limits
• Read further and contact support

Prepare a cleanup policy

Ask the person responsible for your website’s data to agree on the retention periods before an administrator enables deletion.

1. As an administrator responsible for backups, create a database backup.
2. Back up the site files, including uploaded files and any separate file-storage locations.
3. Confirm that those backups can be restored through your hosting or backup system.
4. Decide which stored data should expire and which data should remain untouched.

Warning: Deleted submissions, files and page versions can only be recovered from a suitable backup. Choose the periods before activating cleanup.

Data Retention requires Concrete CMS 9.3.0 or newer and a PHP version supported by your Concrete release. It does not require another add-on or separately installed libraries.

A retention period makes records older than its cutoff eligible. Express and legacy submissions use their creation dates; database logs use their recorded timestamps. For each category, Never delete automatically excludes that category from this add-on’s cleanup.

Nothing is enabled by default. Saving an active policy creates its schedule. If the server scheduler is already running, that policy can execute at its next scheduled time.

Install the add-on

1. Sign in with an administrator account permitted to install add-ons.
2. Download Data Retention through your connected Marketplace account, or obtain its installation ZIP.
3. For a ZIP installation, extract the xw_data_retention folder into your site’s packages/ directory.
4. For a ZIP installation, confirm that packages/xw_data_retention/controller.php exists.
5. Open Dashboard → Extend Concrete → Install.
6. Under Awaiting Installation, click Install for the downloaded package.
7. Open Dashboard → System & Settings → Automation → Data Retention.

The Data Retention page now contains one form for submissions, uploads and logs, and another form for page versions. Installation also adds two native tasks and the add-on’s run-counter table. It does not delete existing data or activate either cleanup schedule.

Set retention periods for forms and logs

Warning: Saving a positive retention period authorizes permanent deletion at the next run. Use a period agreed for your site and keep a current backup.

1. With an administrator account allowed to access Data Retention, open Dashboard → System & Settings → Automation → Data Retention.
2. Under Express Form submissions, select the required period or Never delete automatically.
3. Under Legacy Form block submissions, select the required period or Never delete automatically.
4. Under Concrete CMS database logs, select the required period or Never delete automatically.
5. When at least one period is active, select I confirm automatic deletion of the selected data types. Deletion cannot be undone.
6. Click Save settings.
7. Read Currently expired beneath each category to see the count for the saved policy.

The available periods are 1, 2, 3, 6, 12, 24 and 36 months. Each category has its own period. The preview uses saved settings; changing a field alone does not update the policy or its counts.

Preview counts are estimates. Time limits, errors, deletion-event vetoes and concurrent changes can reduce what the next run deletes.

The categories cover different records:

• Express Form submissions covers entries belonging to entities used by installed Express Form blocks. Unrelated Express objects remain untouched.
• Legacy Form block submissions covers stored answer sets and answers from the classic Form block.
• Concrete CMS database logs covers old records in Concrete’s database log. This includes logged copies of sent mail when Concrete stores them there.

A positive period creates the form/log schedule for 03:10. Set up the server trigger under “Schedule automatic cleanup” before relying on automatic execution.

Delete uploads from expired Express submissions

Warning: Eligible files are deleted with all their versions and thumbnails. Use a dedicated upload folder and do not reuse its files elsewhere.

1. Sign in as an administrator allowed to manage File Manager folders and edit the Express Form block.
2. In File Manager, create a dedicated folder for that form’s uploads, such as “Application uploads”.
3. Open the Express Form block’s editing form.
4. Select Options.
5. Under Files → Add uploaded files to folder, select the dedicated folder.
6. Save the Form block’s settings.
7. With an administrator account allowed to access Data Retention, open Dashboard → System & Settings → Automation → Data Retention.
8. Under Express Form submissions, select a positive retention period.
9. Under Authorized upload folder, select the same folder used by the Form block.
10. Select Also delete uploaded files.
11. Select I confirm that uploaded files in this folder that belong to expired Express entries will be permanently deleted.
12. Select the main automatic-deletion confirmation beneath the retention fields.
13. Click Save settings.
14. Read Currently eligible uploaded files to see the saved policy’s file count.

The upload option is available only with a positive Express retention period and an authorized folder other than the File Manager root. A folder selection alone does not enable cleanup.

A file is eligible only when both conditions hold:

• It is attached through a standard file attribute to an expired Express entry being deleted.
• It is directly inside the authorized folder.

Subfolders, other folders and files with no Express link are excluded. After deleting an expired entry, the add-on checks remaining Express entries, including unrelated entities. A remaining reference protects the file. Recorded Core page or block usage also protects it.

Core’s usage tracker cannot detect every hard-coded file URL or custom integration. A dedicated folder and avoiding reuse are necessary even when reference checks are enabled.

Changing Add uploaded files to folder affects new uploads. It does not move earlier uploads into the authorized folder.

Store confidential uploads privately

Warning: A retention period does not make an uploaded file private. Confidential files need non-public storage and appropriate download permissions while they remain stored.

1. Sign in as an administrator allowed to manage file storage locations and File Manager permissions.
2. Open Dashboard → System & Settings → Files → File Storage Locations.
3. Add a non-public storage location for the uploads. For local storage, use a directory outside the public web root without a public relative URL.
4. In File Manager, open Edit Folder for the dedicated upload folder.
5. Under Storage Location, assign the non-public location to that folder.
6. Review which users and groups can download files from the folder and restrict those permissions to the intended recipients.

New uploads moved into that folder use its storage location. Changing the folder setting does not migrate existing files.

For an existing confidential file, an administrator with permission to edit its file permissions can open the file’s details. Under Storage, click Edit to change its storage location. Move existing files to the private location separately, then confirm their download permissions.

Non-public storage prevents a direct public file URL. Concrete can still serve downloads according to its permissions.

Retain and delete old page versions

Warning: Deleted page versions require a backup to recover. Disable the schedule for Core’s Remove Old Page Versions task before using this policy.

1. With an administrator account allowed to access scheduled tasks, open Dashboard → System & Settings → Automation → Schedule.
2. If Remove Old Page Versions appears in the schedule, click its trash icon.
3. Confirm Delete for that scheduled task.
4. With an administrator account allowed to access Data Retention, open Dashboard → System & Settings → Automation → Data Retention.
5. In Page versions → Automatic page version cleanup, select Delete old page versions automatically.
6. In Minimum versions to keep per page, enter the required minimum, such as “20”. The permitted range is 10–1000.
7. In Additionally delete only versions older than, select an age limit or No age limit.
8. To include stack and global-area histories, select Also clean up stacks and global areas. Leave it unselected to exclude them.
9. Select the deletion confirmation within the Page versions form.
10. Click Save page version settings.
11. Read Currently eligible to see the eligible version count and the number of affected pages.

The age choices are 1, 2, 3, 6, 12, 24 and 36 months. A version must fall outside the newest N versions and satisfy the age limit. The age limit uses the version’s creation date.

With a minimum of 20 versions and a 12-month limit, the newest 20 remain regardless of age. History outside those 20 is eligible only when it is also older than 12 months and has no additional protection.

The add-on always retains:

• The newest version.
• Every approved version.
• Versions with a future publication start.
• Every version on a page with an open workflow.

An open workflow excludes the entire page until the workflow completes. These protections and the age condition can leave more than the configured minimum.

Trash, composer drafts, Dashboard/system pages, aliases and page templates are excluded. Stack and global-area histories require the separate opt-in and follow the same protection rules. Each language page is evaluated independently.

Core’s Remove Old Page Versions task independently retains the newest ten plus its protected versions. It does not use this add-on’s count, age or open-workflow policy. Running both tasks can remove history that your Data Retention settings would retain. The settings page displays a warning while that Core task has a schedule.

The page-version policy creates its own 03:40 schedule. It does not change the form/log policy or its upload folder.

Schedule automatic cleanup

1. Sign in as an administrator allowed to change automation settings.
2. Open Dashboard → System & Settings → Automation → Automation Settings.
3. Under Scheduler, select Enabled - Schedule tasks when running them.
4. Click Save.
5. Ask the server administrator or hosting provider to configure the scheduler command to run every minute with the site’s supported PHP executable and filesystem user.
6. Open Dashboard → System & Settings → Automation → Schedule with an administrator account allowed to view scheduled tasks.
7. Confirm that the enabled Data Retention policies have the expected schedules.

The schedules are independent:

• Delete expired form data runs at 03:10 while at least one Express, legacy or database-log period is active. It includes optional Express upload cleanup.
• Delete old page versions runs at 03:40 while page-version cleanup is enabled.

The times use Concrete’s configured server timezone. The server command is given under “Run commands on the server”. It evaluates all due Concrete schedules, not just Data Retention.

Enabling the Scheduler setting or saving a policy does not create a server cron entry. The hosting configuration must invoke the scheduler command.

Run a cleanup manually

Warning: Run Task performs real deletion using the saved policy. Read the current preview and confirm that a suitable backup exists before starting it.

1. With an administrator account allowed to access Data Retention, open its settings page.
2. Read the eligible counts for the policy you want to run.
3. With an administrator account allowed to run tasks, open Dashboard → System & Settings → Automation → Tasks.
4. Select Delete expired form data or Delete old page versions.
5. If the Scheduler is enabled, select Now under Run Task.
6. Click Run Task.
7. Open Dashboard → System & Settings → Automation → Activity with an administrator account allowed to view task activity.
8. Follow the process until it completes or reports a failure.

Manual runs respect the saved enable/disable settings and protection rules. Running a task does not enable a disabled policy.

Form submissions are processed in batches until complete or until the task reaches its time limit. Remaining expired entries can continue on a later run. Database logs are processed in batches until complete.

Keep and read task logs

Warning: Process log files must be stored outside a publicly readable directory.

1. With an administrator account allowed to change automation settings, open Dashboard → System & Settings → Automation → Automation Settings.
2. Under Logging, select the File option.
3. In Log Directory, enter an existing directory that the web server can write to. End the path with a slash.
4. Click Save.
5. After a cleanup run, open Dashboard → System & Settings → Automation → Activity with an administrator account allowed to view activity.
6. Open the process details to read the retained output.

The form task reports deleted Express entries, uploaded files, legacy submissions and database logs. The page-version task reports deleted versions and processed pages. File/version errors use the xw_data_retention log channel. To inspect those errors, open Dashboard → Reports → Logs and look for that channel.

Without file process logging, full process output is not retained. Task status remains available through the Core task interface.

Stop future cleanup

1. With an administrator account allowed to access Data Retention, open Dashboard → System & Settings → Automation → Data Retention.
2. To stop form/log cleanup, set Express Form submissions to Never delete automatically.
3. Set Legacy Form block submissions to Never delete automatically.
4. Set Concrete CMS database logs to Never delete automatically.
5. Click Save settings.
6. In Page versions → Automatic page version cleanup, select Never delete automatically to stop page-history cleanup.
7. Click Save page version settings.

The add-on removes each disabled policy’s schedule without changing the other policy.

To keep entry cleanup but stop upload deletion, clear Also delete uploaded files in the first form. Accept the main confirmation if a retention period remains active, then click Save settings.

Saving disabled settings controls future cleanup; it does not restore deleted data. If a process is already active, view it under Dashboard → System & Settings → Automation → Activity. Removing a future schedule does not by itself cancel an active process.

Upgrade the add-on

1. As an administrator responsible for the site’s backups, create a current database and file backup.
2. Replace the files in packages/xw_data_retention/ with the 0.9.3 package.
3. With an administrator account permitted to update add-ons, open Dashboard → Extend Concrete → Update Add-Ons.
4. For the downloaded package, click Update Add-On.
5. With an administrator account allowed to access Data Retention, open its settings page.
6. Confirm that the existing Express, legacy and database-log periods still have the intended values.

When upgrading from 0.9.0, those retention periods are preserved. Upload deletion and page-version cleanup start disabled. The upgrade adds the page-version task and the add-on’s run-counter table.

Do not uninstall to apply an upgrade. Uninstallation removes this add-on’s configuration and schedules.

Uninstall the add-on

Warning: Uninstallation removes the saved retention settings and schedules. Keep a backup if you need to restore that configuration later.

1. With an administrator account permitted to uninstall add-ons, open Dashboard → Extend Concrete → Install.
2. Under Currently Installed, click Details for the installed package.
3. Click Uninstall Package.
4. To move the package files out of packages/ as well, select Yes, remove the package's directory from the installation directory.
5. Click Uninstall.

The add-on removes its Dashboard page, both tasks, their schedules, its configuration and its run-counter table. Uninstallation does not execute cleanup of your submissions, uploads or page histories. Core removes the add-on’s own Dashboard page and that page’s history.

Uninstallation does not restore anything previously deleted.

Run commands on the server

Use command-line access only with the server administrator’s permission. Run commands from the site root with a supported PHP executable and a filesystem user allowed to access the site and its storage.

To install a downloaded package:

php concrete/bin/concrete c5:package:install xw_data_retention

To apply a downloaded package update:

php concrete/bin/concrete c5:package:update xw_data_retention

The server administrator can invoke the scheduler every minute with a cron entry:

* * * * * cd /absolute/path/to/site && /absolute/path/to/php concrete/bin/concrete concrete:scheduler:run

Replace /absolute/path/to/site with the site root and /absolute/path/to/php with the correct PHP executable. This scheduler processes all due Concrete tasks.

Warning: The following task commands perform real cleanup according to the saved settings. Use the same preview and backup precautions as a Dashboard run.

php concrete/bin/concrete task:xw-data-retention:delete-expired
php concrete/bin/concrete task:xw-data-retention:delete-page-versions

The internal task handles are xw_delete_expired_form_data and xw_delete_old_page_versions. Include the relevant handle when reporting a task problem.

Resolve common problems

The task does not run automatically.

1. With an administrator account allowed to access Data Retention, confirm that the desired policy is saved and enabled.
2. In Dashboard → System & Settings → Automation → Schedule, locate its scheduled task.
3. In Dashboard → System & Settings → Automation → Automation Settings, confirm that Scheduler is enabled.
4. Ask the server administrator to confirm that cron invokes concrete:scheduler:run every minute with the correct PHP executable and site path.
5. Read the task’s process status under Activity at the scheduled time.

A manual Dashboard task remains queued.

1. With an administrator account allowed to view task activity, open Dashboard → System & Settings → Automation → Activity and locate the process.
2. Open Dashboard → System & Settings → Automation → Failed Messages to look for a processing error.
3. With an administrator account allowed to change automation settings, open Automation Settings and read Queue Listening.
4. With Automatic queue listening, keep the task/activity page open until processing completes. Leaving the page can interrupt automatic processing.
5. With Manual queue listening, ask the server administrator to keep at least one worker running with the site’s PHP executable:

php concrete/bin/concrete messenger:consume async

Do not switch to Manual unless the server worker is configured. This setting affects other queued Core actions as well.

The preview shows zero.

1. Open Data Retention with an administrator account allowed to access its settings.
2. Confirm that the relevant retention period or page-version policy is enabled.
3. Confirm that the records are older than the selected cutoff.
4. For page versions, also account for the newest-N count, approved versions, future publication starts and open workflows.

The preview uses the saved policy. Save a changed setting before expecting the preview to reflect it.

The task deletes fewer records than the preview showed.

1. Open the process details under Activity with an administrator account allowed to view them.
2. Read the deletion totals and any reported failure.
3. Compare the saved policy and current references with the earlier preview.
4. Run the task again only after confirming that the remaining records are still eligible and a current backup exists.

A time limit, deletion-event veto, failure or concurrent change can reduce the total. Remaining expired form entries can continue on a later run.

Uploads remain after an Express entry was deleted.

1. In Data Retention, confirm the saved Also delete uploaded files setting and Authorized upload folder.
2. In File Manager, confirm that the file is directly inside that folder, not a subfolder.
3. Look for remaining Express references or recorded page/block usage.
4. Read xw_data_retention errors under Dashboard → Reports → Logs.

If the authorized folder was removed, the add-on skips file cleanup but can still delete expired entries. A file with no qualifying Express link is not swept.

If a file deletion fails or a Core event vetoes it, later files continue. The removed entry can leave that file unlinked. Unlinked files are not automatically retried; review them separately in File Manager.

More than N page versions remain.

In Data Retention, read the saved age limit and count. Approved versions, future publication starts and open workflows provide additional protection. N is a minimum to retain, not a strict final count.

Understand the scope and limits

Data Retention does not manage delivered emails in mailboxes, external web-server logs, external analytics or backups. Database-log cleanup does include mail copies stored in Concrete’s own log table.

Optional upload cleanup does not cover legacy Form uploads, unrelated File Manager files or files outside its authorized scope. Files stored outside Concrete’s File Manager are not managed by this policy. Other Core tasks and tools can have independent deletion rules.

Published page content is protected by the page-version policy. The policy does not replace a database and file backup.

Retention periods are technical settings. They do not determine your organization’s legal retention duties or certify compliance.

The interface uses translatable English strings. German source translations are maintained outside the installable package. The package does not bundle PO/MO files.

Once a catalog is published through the Concrete translation service:

1. With an administrator account allowed to update languages, open Dashboard → System & Settings → Basics → Languages.
2. Click Install/Update Languages.
3. On Update Languages, expand the entry for this add-on.
4. For the required language, click Install under Installable languages, or Update under Updates to installed languages.

Read further and contact support

• Data Retention source and README (external link) — package files, installation reference and project information.
• German README (external link) — the package reference in German.
• Concrete translation service (external link) — published language catalogs and translation contributions.

Publisher: Xanweb GmbH. Data Retention is free and distributed under the MIT license.

Report a reproducible problem through GitHub Issues (external link). Include the Concrete version, PHP version, add-on version, relevant saved settings, task handle, process output and reproduction steps. Remove credentials and personal submission data from logs before sharing them. Support has no guaranteed response time.

Source: Data Retention 0.9.3 package source and Concrete CMS 9.5.7 · Interface language: English