Cleaning up the repository

Use the REST API cleanup tool to remove versions of items in the Decision Center repository. The cleanup tool permanently deletes items from the repository, whereas the archiving tool leaves old data available in the database.

The cleanup tool deletes items that include baselines, reports, and versions of elements. You can run the tool in the background while continuing to use the Business console.

The tool can be stopped at any time. If you stop the tool, any items already deleted cannot be recovered. The process can be restarted to remove the remaining items.

The run time for the tool depends on the number of items in the repository. The tool must search the repository for items that meet the criteria for deletion, and then remove them. The larger the repository, the longer the run time.

The criteria for deletion mainly depends on a date argument (cleanupDate). Elements that are older than the date can be selected for deletion. All the baseline types, including snapshots, branches, and managed branches, are also handled by the cleanup tool according to this date argument. However, the behavior of the tool depends on the baseline type. A snapshot handles references to element versions, while a branch is a container that holds element versions. A snapshot is removed if its date is older than the cleanup date, but the element versions that are referenced by the snapshot are not affected by the removal of the snapshot. Conversely, dropping a branch removes all the element versions in the branch. A branch is removed by the tool only if its date is old enough, and if it does not contain a recently updated element, including in subbranches if any.

In a cluster, you might want to dedicate a node to running the cleanup tool. The tool uses memory to store the cleanup report, which is not persisted to the database. Other nodes in the cluster cannot get the report information, but they can run operations to check that the tool is running, and to stop the execution. These operations use information that is stored in the repository that is shared by the cluster nodes.

To reduce the risk of unwanted deletions, the cleanup service is not enabled by default. To use the tool, the service must be enabled by setting the system property com.ibm.rules.decisioncenter.enableCleanupService to true in the server startup configuration. For a cluster setup, the service must be enabled for each node that uses the tool. When the system property is set, the server must be restarted to launch the cleanup service. The server log file then shows the following message:

INFO: Service 'Decision Center Repository Cleanup Service' is available.
Tip: Before running the cleanup tool, back up your repository. The changes made by the tool cannot be reversed.

Running the cleanup tool

The cleanup tool is part of the Decision Center REST API. You run the tool through certain endpoints. Follow these steps:

  1. Open the Decision Center REST API.
  2. Run the cleanup tool by using the /v1/DBAdmin/cleanup/launch endpoint with the following parameters:
    • datasource: The JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.
    • cleanupDate: Items that have versions older than the cleanup date are deleted. However, if an item is older than the cleanup date but it is the latest version of that item, the item is not deleted. For example, if the cleanup tool is set to delete items older than five years, and a rule in the repository is 10 years old but has never been updated, the cleanup tool does not delete the rule because it is the latest version for the rule.
    • dryRun: (Optional) When this parameter is set to true, the cleanup tool creates a report, but it does not delete items in the repository. You can use the report to see which items would be deleted. By default, dryRun is set to false to delete the items.
    • recyclebinMode: (Optional) When this parameter is set to true, the cleanup tool only removes the references to items from the recycle bin. It cleans the recycle bin, but it does not remove items from the repository.
      Note: The cleanup tool might not remove some elements in the recycle bin even if the displayed date is older than the cleanup date (cleanupDate). The recycle bin shows the date on which an element was last modified, and not the deletion date of the element. The deletion date is only displayed when using the timeline, and the cleanup tool uses the deletion date when it looks at the recycle bin. For example, if the creation version of an element is 10 years old, and its deletion date is only one year old, the element is not removed from the recycle bin if the cleanup date is set to five years ago.
    • eclassFQN: (Optional) You can indicate an element type to delete items of that type only. By default, all versionable element types are processed. To select a specific element type, enter one of these values: brm.RuleArtifact, brm.Ruleflow, brm.VariableSet, brm.RulePackage, brm.AbstractQuery, brm.Baseline, brm.BOM, brm.BOM2XOMMapping, brm.DecisionModel, brm.Vocabulary, brm.Template, brm.ScenarioSuite, brm.Resource, brm.EventElement, dsm.Deployment, dsm.Operation, dsm.DSDeploymentReport, validation.Metric, validation.KPI, validation.SimulationModel, validation.SimulationConfiguration, validation.SimulationReport, validation.InputData, validation.TestSuite, validation.TestReport, or validation.TestCase.
    • handleReports: (Optional) Set to true to include reports in the cleanup. The types of reports include TestSuite, Simulation, and Deployment reports. By default, this option is set to false to retain the reports.
      Tip: To clean up a specific report class, you must set handleReports to true, and set the eclassFQN argument to the report class. For example, for old deployment report entries, set the eclassFQN argument to dsm.DSDeploymentReport. Also note that setting the eclassFQN argument to a report class only works when the handleReports argument is on. If handleReports is switched on, but eclassFQN is set to a class that is not a report class, no report entries are cleared. In this case, only the elements for the given eclassFQN value are handled. Also, if both recyclebinMode and handleReports are set to true, no report entries are cleared because the recycle bin does not reference report entries.
  3. Check /v1/DBAdmin/cleanup/status to see whether the cleanup operation is running. It shows a status of true or false for running or not, respectively, and the cleanup date and element type provided for the current execution or the latest execution if any.
  4. Get the cleanup report by using /v1/DBAdmin/cleanup/report. It returns a JSON file that shows the items selected by the cleanup tool. The report can be opened at any time, even when the tool is running.

    If you are not using dryRun and you open the report while the cleanup tool is running, the report shows the selected items that have already been deleted in the run. You cannot retrieve deleted items.

  5. Stop the cleanup tool by using /v1/DBAdmin/cleanup/stop. The cleanup tool stops after finishing its current operation. You can restart the cleanup tool to continue deleting items.
  6. Get old cleanup reports by using /v1/DBAdmin/cleanup/oldreports. It returns a JSON file that contains a list of reports for previous runs of the tool. The file does not include the report for the latest run, which you get with /v1/DBAdmin/cleanup/report. The number of old reports kept by the tool can be customized by using the global user setting decisioncenter.internal.cleanupservice.oldreportscount. By default, the tool keeps a maximum of 10 reports in memory. The list is sorted according to the execution timestamp from the most recent to the oldest report.

REST API cleanup tool description

The following tables show the endpoints for the cleanup tool and their parameters.

Table 1. GET operations
Endpoint Parameter
/v1/DBAdmin/cleanup/report datasource: (Optional) A string value for the JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.
/v1/DBAdmin/cleanup/status datasource: (Optional) A string value for the JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.
/v1/DBAdmin/cleanup/oldreports datasource: (Optional) A string value for the JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.
Table 2. POST operations
Endpoint Parameter
/v1/DBAdmin/cleanup/launch
  • cleanupDate: (Required) A string value that uses the date format YYYY-MMM-DD, with MMM= Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec.
  • datasource: (Optional) A string value for the JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.
  • dryRun: (Optional) A boolean value set to false by default. Set to true to create a cleanup report without deleting items in the repository.
  • handleReports: (Optional) A boolean value set to false by default. Set to true to include reports in the cleanup.
  • recyclebinMode: (Optional) A boolean value set to false by default. Set to true to delete only the contents of the recycle bin.
  • eclassFQN: (Optional) A string value to specify the type of item to delete. If not specified, all types are subject to deletion.
/v1/DBAdmin/cleanup/stop datasource: (Optional) A string value for the JNDI name of the Decision Center data source. If not specified, it defaults to jdbc/ilogDataSource.

Cleanup report

The report operation accesses report information that is available for only the node that started the operation. The endpoint must be the same as the one used for the launch operation.

The cleanup report shows information about a run. The report can cover the latest cleanup or a cleanup that is currently running. The report includes the following information:

Execution options
These options are specified for the cleanup operation:
  • datasourceName: The string value for the JNDI name of the Decision Center data source. If not specified, the report shows jdbc/ilogDataSource.
  • cleanupDate: The string value for the date specified for selecting items to delete.
  • dryRun: A boolean value, it is set to true to check the repository without deletion. By default, it is set to false for deletion.
  • handleReports: A boolean value, it set to true to process reports. By default, it is set to false to retain reports.
  • recyclebinMode: A boolean value, it is set to true when only the items in the recycle bin of the branches should be deleted. By default, it is set to false to process all items.
  • eclassFQN: A string value, it is the element type to process when a value is specified for running the operation.
Execution status
States the status of the cleanup operation:
  • launchTimestamp: A timestamp that indicates when the cleanup operation was launched.
  • completed: A boolean value, it is set to true when tool execution is completed.
  • exceptions: A list of string values, it shows exception messages for any errors from running the tool.
  • messages: A list of string values, it might be displayed to show information messages, for example, details about an unexpected combination of options.
  • stopped: A boolean value, it is set to true when a cleanup is stopped before all the items that meet the criteria are processed.
List of deleted versions (deletedVEltInfo attribute)

Shows the versions that were selected by the cleanup tool based on the launch options:

  • versionId: Integer that shows the identifier of the deleted version
  • versDate: Timestamp that shows the version creation date
  • major: Integer that shows the major version value
  • minor: Integer that shows the minor version value
  • isDeletionVers: Boolean that is true when this version was created for the deletion of this item
  • uuid: String value for the UUID of this item
  • eltOId: Integer that gives the original identifier of the element for this version
  • eltId: Integer that gives the identifier of the element for this version
  • typeFQN: String value for the type of the item for this version
  • eltName: String value for the name of the item for this version
  • prjId: Integer that gives the identifier of the project of this item
  • projectName: String value for the name of the project of this item
  • branchId: Integer that gives the identifier of the branch
List of deleted baselines (deletedBaselines attribute)

Shows the baselines that were selected by the cleanup tool based on the launch options:

  • name: String value for the name of this baseline
  • uuid: String value for the UUID of this baseline
  • id: Integer that gives the identifier of the element for this baseline
  • typeFQN: String value for the type of the item for this baseline
  • parentId: Integer that gives the identifier of the parent of this baseline
  • kind: String for Branch, Deployment, DsDeployment, Migrated, Standard, or Temporary
  • createdon: Timestamp that shows the baseline creation date
  • prjName: String value for the name of the project of this baseline
List of deleted elements (deletedElt attribute)

Shows the nonversioned elements that were selected by the cleanup tool based on the launch options (occurs when the handleReports option is set to true):

  • eltName: String value for the name of the item for this report
  • eltId: Integer that gives the identifier of the element for this report
  • typeFQN: String value for the type of the item for this report (dsm.DSDeploymentReport, validation.SimulationReport, or validation.TestReport)
  • createdon: Timestamp that shows the report creation date
  • prjName: String value for the name of the project of this report