Working with the Clean-up Utility

The Clean-up Utility DB-Cleanup.exe is a command line utility that can be used to delete workflow Executions and History Records in the database.

Important! Stop the Release Manager before running the DB-Cleanup tool to avoid conflicts in the database.

This page includes the following:

About the Clean-up Utility

After running CDA for a while, the CDA database may contain an increasing number of outdated records, especially from workflow executions. To keep the size of the Continuous Delivery Automation database small and ensure a good performance, you may want to remove outdated records. To do so, you can run the Clean-up Utility.

Important! The Clean-up Utility requires a direct database connection and operates through SQL statements. Therefore, the computer hosting the utility must allow a connection to the CDA database server.

The user specified in the connection string must have CRUD privileges on all tables of the CDA database and the right to create temporary tables in the database.

Installing the Clean-up Utility

If the Clean-up utility DB-Cleanup.exe is not already available on your system, perform the following steps.

To Install the Clean-Up Utility

Tip: Save the Clean-Up Utility in the following folder: C:\Automic\Release.Manager\Utilities

  1. Copy the DB-Cleanup.exe file to a machine which has access to the CDA database server.
  2. Configure the clean-up utility according to your needs.

    See :Configuring the DB-Cleanup.exe.config File

Configuring the DB-Cleanup.exe.config File

Note: The DB-Cleanup.exe.config file must be stored in the same folder as the DB-Cleanup.exe.

The parameters are organized in the following sections:

Both sections can be encrypted.

Tip: You can set fixed parameters (for example, Application names) with <add key> tags. For example: <add key "applications" value="MyApp1,MyApp2">

Parameters

You can pass every parameter either via XML configuration file Db-Cleanup.exe.config or directly together with the command line call (Both, dash- and colon-syntax are supported to pass parameters).

Rules for combining parameters:

Case-sensitivity of parameters depends on the underlying database:

Available Commands

You can run the following commands:

Important! If no command is specified, executions are cleaned up.

Examples

\DB-Cleanup.exe historyrecord

Input Parameters

Common Parameters

The table below lists the inputs input parameters available for all commands:

Available for Parameter Mandatory Type Default Description / Help message in CLI
All commands connectionString Yes String -

Connection string to connect to the CDA database.

See also:Configuring the Web Application - Customer.Config
All commands verbose No string min

Level of textual output to the screen or to a log file.

Possible values:

  • min: minimal - only errors and warnings are reported.
  • med: medium - errors + warnings + infos are reported.
  • max: Maximum - all log messages are reported (for debugging).
All commands fi No string -

(Optional) mirrors screen output including timestamps to a log file.
All commands No - -

Displays the parameters and their description for the DB Clean-up tool.
All commands olderThan No Number 90

Only entities having an end-date older than the specified number of days before the current date are deleted.

Important! Only whole days are selected.

Example:

  • Current date and time is 2014-05-15 10:12
  • Parameter olderThan is set to 1
  • Calculation: 2014-05-15 00:00 - 1 (olderThan value) = 2014-05-14 00:00
  • Results: all executions with an end date prior to 2014-05-14 00:00 are considered for deletion

Note: olderThan=0 means that all entities are deleted.

Default: 90
All commands keepAtLeast No Number

Defines how many entities must remain per parent entity.

Example:

keepAtLeast=20 means that at least the 20 latest history records of each parent entity remain in the system and are not deleted - even if they match the olderThan or some other criteria.

\DB-Cleanup.exe historyrecord --olderThan 120 --keepAtLeast 20

Default values:

  • execution: 5
  • package: 5
  • artifact: 5
  • historyrecord: 15

Command-specific Parameters

Executions

Command name: execution

Parameter Mandatory Type Default Description / Help message in CLI
applications No String -

Comma-separated list of application names.

If set, only executions of the specified applications are considered to be deleted.

Example:

CRM System, Billing System
workflows No String -

Comma-separated list of workflow names.

Note: For application workflows, this parameters has to be set together with the applications parameter. If the applications parameter is not set, only general workflows are considered to be deleted.

Example:

Install, Uninstall.
archivedOnly No Boolean false

Flag forcing whether all executions or only archived ones should be considered to be deleted.

Values:

  • true: Only archived executions are considered to be deleted.
  • false: All executions are considered to be deleted.
force No Boolean false

Flag forcing whether the utility should also consider to delete executions that belong to a current installation or not.

Values:

  • true: Also executions belonging to current installations are considered to be deleted.
  • false: Executions belonging to current installations are not deleted.
id No string -

Comma-separated id of executions to be deleted. The number of Ids to be specified is limited to 100.

This switch cannot be used together with any of the other filtering switches (olderThan, keepAtLeast, applications, workflows, archivedOnly).

If an invalid value for a parameter is defined, the tool prints an error message and quits.

Conditions for Deleting Executions

The Clean-up Utility only deletes a record if all of the following conditions are fulfilled:

Packages

Command name: package

Parameter Mandatory Type Default Description / Help message in CLI
applications No String -

Comma-separated list of application names.

If set, only executions of the specified applications are considered to be deleted.

Example:

CRM System, Billing System
archivedOnly No Boolean false

Flag forcing whether all packages or only archived packages should be considered to be deleted.

Values:

  • true: Only archived packages are considered to be deleted.
  • false: All packages are considered to be deleted.
force No Boolean false

Flag forcing whether the utility should also consider to delete packages that belong to old installations.

Values:

  • true: Packages belonging to old installations are considered to be deleted. Old installation records are deleted along with Packages.
  • false: Only unused packages, that is, packages not belonging to any installation, are considered to be deleted.
id No string -

Comma-separated id of packages to be deleted. The number of Ids to be specified is limited to 100.

This switch cannot be used in conjunction with any of the other filtering switches (olderThan, keepAtLeast, applications, workflows, archivedOnly).

If an invalid value for a parameter is defined, the tool prints an error message and quits.

Conditions for Deleting Packages

The Clean-up Utility only deletes a record if all of the following conditions are fulfilled:

Artifacts

Command name: artifact

Parameter Mandatory Type Default Description / Help message in CLI
sources No String -

Comma-separated list of Artifact Source names.

If set, only Artifacts of the specified Artifact Sources are considered to be deleted.

Example: "Internal Nexus,Department SMB".
archivedOnly No Boolean false

Flag forcing whether all artifacts or only archived artifacts should be considered to be deleted.

Values:

  • true: Only archived artifacts are considered to be deleted.
  • false: All artifacts are considered to be deleted.
force No Boolean false

Flag forcing whether the utility should also consider to delete artifacts that belong to old installations.

Values:

  • true: Artifacts belonging to old installations are considered to be deleted.
  • false: Only unused Artifacts are considered to be deleted.
id No string -

Comma-separated id of artifacts to be deleted. The number of Ids to be specified is limited to 100.

This switch cannot be used in conjunction with any of the other filtering switches (olderThan, keepAtLeast, applications, workflows, archivedOnly).

If an invalid value for a parameter is defined, the tool prints an error message and quits.

Conditions for Deleting Artifacts

The Clean-up Utility only deletes a record if all of the following conditions are fulfilled:

History Records

Command name: historyrecord

See: Common Parameters

Return Codes

After each run, the Clean-up utility returns an exit code to indicate the outcome of action. You may use this code in a script.

The utility returns the following codes:

Value Meaning
0 Success
1 Unable to connect to the database
99

Unexpected error

Note: To resolve this, check the log files.

Configuration Files

Common parameters can be specified in the configuration file with the same name as in the command line parameter.

<appSettings>
   <add key="verbose" value="max" />
   <add key="force" value="false" />
 </appSettings>

Command-specific parameters have the following format: [commandname].<parameter_name>

Example:

<appSettings>
   <add key="verbose" value="max" />
   <add key="force" value="false" />
   <add key="package.keepAtLeast" value="100" />
   <add key="package.olderThan" value="90" />
 </appSettings>

Command-specific parameters without prefix are considered as execution parameters:

<appSettings>
   <add key="verbose" value="max" />
   <add key="force" value="false" />
   <add key="keepAtLeast" value="100" /> <!-- this is considered as an execution command parameter -->
 </appSettings>

Examples

Examples for CLI calls and configuration file

Dash-syntax:

\DB-Cleanup.exe --olderThan 120 --archivedOnly true --applications "CRM System"

Colon-syntax:

\DB-Cleanup.exe olderThan:120 archivedOnly:true applications: "CRM System"

DB-Cleanup.exe.config:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

<connectionStrings> <add name="Database" connectionString="Data Source=##DB SERVER##;Initial Catalog=##DB NAME##;User ID=##DB USER##;Password=##DB PASSWORD##"/> </connectionStrings>

<appSettings> <add key="verbose" value="max"/> <add key="force" value="false"/> </appSettings>

</configuration>

See also: