Delete Expired Objects

Overview

This guide describes how to use a task stage hook to delete expired executions, workflows, tasks, and Icebox Generations.

The task stage hook provides a single point of control for cleaning up old XDM objects.

Before using this task stage hook, decide how long objects should be kept in XDM:

  • Executions, workflows, and tasks may be kept for auditing purposes, for example to check what data was copied and when.

  • They may also be kept to rerun a specific execution.

  • Icebox Generations are usually kept as long as the stored data is needed.

For Icebox Generations, this guide uses the Backup retention period instead of only the creation date. The Backup retention period is stored in the variable iceboxRetentionPeriod.

It can be configured:

  • for all Icebox Generations of a task template, or

  • individually for each Icebox Generation.

Prerequisites

Before creating the cleanup hook, make sure the following requirements are met.

Required Permissions

The user executing the task stage hook needs read permissions for:

  • the executed task list,

  • the workflow template list,

  • all task template lists.

The user also needs read and delete permissions for:

  • all executions,

  • all workflow templates,

  • all task templates.

Backup Retention Period for Icebox Generations

For Icebox Generations, the Backup retention period is used to define how long an Icebox Generation should be stored.

For more details, see retention description.

The Backup retention period is also used by XDM itself to delete Icebox Generations. To use an individual date, add a custom parameter to the Icebox Generation and customize the delete task stage hook.

Environment ID

To run this task stage hook on different XDM environments, configure an environment-id for each XDM instance.

The script can then use this value to detect on which instance the workflow currently runs and apply environment-specific settings.

For setup details, see Setup EnvironmentId as Environment variable.

Steps

Step 1: Create the Task Stage Hook

Create a task stage hook that identifies old or expired XDM objects and deletes them.

The task stage hook iterates over:

  • Executions

  • Workflow Templates

  • Task Templates

  • Icebox Generations

For executions, workflows, and tasks, the last execution timestamp is used to decide whether the object should be deleted.

For Icebox Generations, the Backup retention period is used.

Step 2: Configure the Cleanup Settings

The hook uses the following settings:

  • retentionPeriod: Defines how long a workflow, task, or execution should be kept.

  • retentionCount: Defines how many workflows and tasks should be kept at minimum per template.

  • implicitOnly: Defines whether only implicitly created tasks and workflows should be deleted.

  • dryRun: Defines whether the hook should only generate a list of objects that would be deleted.

Step 3: Customize the Hook per Environment

The complete hook and an example workflow can be downloaded here:

Delete Expired Objects & Workflow call

The following part of the task stage hook customizes the cleanup behavior.

The variables control:

  • which objects are deleted,

  • which objects are kept,

  • whether the hook runs in dry-run mode,

  • whether different environments use different retention settings.

The example sets default values and overrides them for specific environments.

def retentionPeriod = "P730D"                       // The period how long a workflow, task or execution should be kept
def retentionCount = 250                            // How many workflows and tasks should be kept at minimum per template
def implicitOnly = true                             // Specifies if only implicitly created tasks and workflows should be deleted
def dryRun = true                                   // Specifies if only a dry run will be done generating a list of objects that should be deleted

/*
 * Switch settings based on the current XDM instance
 */
def environment = System.getenv("xdm.core.environment-id")
switch (environment) {
    case 'int':
        retentionPeriod = "P30D"
        retentionCount = 30
        //implicitOnly = true
        //dryRun = true
        break

    case 'dev':
        retentionPeriod = "P30D"
        retentionCount = 30
        //implicitOnly = true
        //dryRun = true
        break

    default: // The default values that will be used for all other environments like prod
        retentionPeriod = "P250D"
        retentionCount = 730
        //implicitOnly = true
        //dryRun = true
        break
}
If the original hook uses the variable name implizitOnly, keep the same variable name in the code or update all references in the full script accordingly.

Step 4: Schedule the Cleanup Workflow

Use the workflow shipped with the task stage hook to execute the cleanup process.

Schedule the workflow to run regularly, for example once per day.

Before activating deletion, run the hook with:

def dryRun = true

Review the generated list of objects that would be deleted.

After validation, switch to:

def dryRun = false

Benefits

This approach provides a central cleanup mechanism for old XDM objects.

Benefits:

  • Old executions, workflows, tasks, and Icebox Generations can be cleaned up automatically.

  • Old cleanup hooks no longer need to be added to each individual workflow template or task template.

  • XDM stays easier to maintain and cleaner over time.

Conclusion

Use this task stage hook when old executions, workflows, tasks, and Icebox Generations should be deleted regularly.

The approach replaces separate cleanup hooks on individual workflow and task templates with one central cleanup process.

This makes the cleanup easier to control, safer to validate, and simpler to maintain.