How Archiving Works

Archiving in Digital.ai Release is a two-stage process that manages completed and aborted releases:

1. Pre-archiving: When a release is completed or aborted, an archiving cron job runs (by default, every minute) to scan for such releases. It copies them to the archive database, but leaves a copy in the operational (live) database. This allows for unified reporting and access to recent releases.
2. Final archiving: According to the configured archiving schedule and age, the archiving cron job scans for completed/aborted releases that are older than the archiving age (see Archiving Job Configuration). These releases are then archived (if not already) and deleted from the operational database, leaving only the archived copy.

This process improves system performance and enables custom export hooks for integration with external databases or reporting tools.

note

Pre-archived releases (still present in the operational database) remain visible in dashboards, filters, and release overviews. Once a release is fully archived (removed from the operational database), it is available in the Archive tab of the Releases page.

• Archived releases are read-only. You cannot add comments to tasks in an archived release.
• Archived releases appear in reports.
• You can create a custom hook that runs when a release is archived (for example, to store the release in an external reporting database).

Archiving Job Configuration

The archiving process in Digital.ai Release is highly configurable. You can control when and how releases are archived, how often the archiving job runs, and how system resources are managed during archiving. The following sections explain the overall archiving flow and the key settings you can adjust to fit your organization's needs.

How Archiving Works

1. Set up the archiving age:

• Go to System Settings > Releases and Triggers and configure the Archive or delete executions older than setting. This is the minimum age (default: 30 days) after which completed or aborted releases are eligible for final archiving or deletion. For more information, see Releases and Workflows Archiving and Clean-up.

2. Pre-archiving:

• A cron job runs every minute by default. It scans for completed and aborted releases and copies them to the archive database, but keeps them in the operational database until they reach the archiving age.

3. Archiving job schedule:

• Set the xlrelease.ArchivingSettings.archivingJobCronSchedule property in deployit-defaults.properties to control how often the archiving job runs (using cron syntax).
• When the archiving cron job runs, it scans for completed/aborted releases older than the archiving age, archives them (if not already), and deletes them from the operational database.

4. Configure throttling and other properties:

• Adjust throttling and performance-related properties to control resource usage and job behavior.

tip

Ensure the archiving job can process at least as many releases per day as are being completed or aborted. For example, do not run the job only once per week unless you adjust throttling properties accordingly. The pre-archiving service runs every minute by default, but the final archiving (deletion from operational database) depends on the archiving job schedule and age.

Throttling Properties

Throttling helps prevent the archiving job from consuming excessive system resources. Configure these properties in deployit-defaults.properties:

Property	Description	Default
xlrelease.ArchivingSettings.maxSecondsPerRun	Max time (seconds) for one archiving job run. With the default, about 18 releases are archived per run. Set to 0 or -1 to remove the limit.	20
xlrelease.ArchivingSettings.sleepSecondsBetweenReleases	Wait time (seconds) between archiving each release. Default: 1 release per second. Set to negative to remove wait.	1
xlrelease.ArchivingSettings.searchPageSize	Number of releases found per search page.	20
xlrelease.ArchivingSettings.enabled	Enables/disables the archiving job. Do not permanently disable.	true

Adjusting Properties at Runtime

You can change throttling properties at runtime using the JMX managed bean at com.xebialabs.xlrelease:name=Archiving. Changes made via JMX are not persisted; after a server restart, file values are restored.

Search Page Size

The searchPageSize property controls how many releases are found per search. For example, if set to 5, the job finds five completed releases, archives them, then searches for the next five, and so on. Increasing this value can speed up archiving large numbers of releases, but may increase CPU usage.

Archive on Demand

By default, every completed or aborted release waits the global age set in Archive or delete executions older than before it is archived or deleted (see Archiving Job Configuration). Archive on Demand lets you override that for individual releases, either by setting a custom age in advance or by requesting archiving for a release that has already finished.

Setting a Custom Archiving or Deletion Age

By default, every release follows a global archiving age set in System Settings. The Archive release after field on a release or template's properties page overrides that global age for this release only or for releases started from this template. Enter a value in hours or days:

• Empty: uses the global age (default; existing releases are unaffected).
• Positive value: release becomes eligible for archiving or deletion that long after it completes or aborts.
• 0: release becomes eligible as soon as it completes or aborts.

When Enable per-release archive or delete is turned on in System Settings > Releases and Triggers, the properties page for a release or template also displays an After completion setting, which decides what happens once the release finishes (completes or aborts):

• Archive release (default): archives the release after the age set in Archive release after. Archiving keeps the release for reporting and moves it off the main Releases list.
• Delete release: deletes the release instead, after the age set in Delete release after. Use this for releases with no lasting value, such as test, development, or utility runs. A deleted release does not appear in reports or in the Archive tab.

When the system setting is disabled, every release is archived when it finishes. For more information, see Releases and Workflows Archiving and Clean-up.

A value set on a template applies to releases started from that template, and each release can override it. These settings also appear on the Create new release page. For more information, see Release Properties.

How to Archive a Release on Demand

For a release that has already finished, you can request archiving instead of waiting for its archiving age to elapse. Archiving can be requested only for releases in the Completed or Aborted state.

Requesting archiving does not archive the release on the spot. It marks the release as eligible for archiving as of the current date and time, and the archiving job picks it up during one of its next runs. How soon this happens depends on the archiving job schedule and the throttling properties.

From the Releases Page

You can request archiving for a single release, or for several releases at once. For the steps, see Archive a Release.

Using the Release API

The Release API accepts requests to mark a release for archiving. The release must be in the Completed or Aborted state when the request is received, and the request must come from a Release administrator. Like the UI action, this marks the release as eligible for archiving rather than archiving it directly.

For more information, see the REST API Reference.

Export Hooks

Digital.ai Release supports custom export hooks to export information about completed and aborted releases. Hooks are triggered when a release is archived.

• Export hooks are written in Jython.
• Add them as JAR files or place them in the Release classpath.

You can define:

• Generic export hooks for exporting to any storage
• JDBC export hooks for exporting to SQL databases

A sample export hook implementation is available on GitHub.