Resource versioning

KUMA stores the change history of resources in the form of versions. A resource version is created automatically when you create a new resource or save changes made to the settings of an existing resource.

The change history is not available for the Dictionaries resource. To save the history of dictionaries, you can export data.

Resource versions are retained for the duration specified in the Settings section. When the age of a resource version reaches the specified value, the version is automatically deleted.

You can view the change history of KUMA resources, compare versions, and restore a previous version of a resource, for example, if it fails and you need to recover it.

To view the change history of a resource:

1. In the KUMA Console, in the Resources section, select the type of resources that you need.

   This opens a window opens with a table of available resources of this type.

   If you want to view all resources, in the Resources section, go to the List tab.

2. Select the check box for the resource whose change history you want to view, and click the Show version history button in the upper part of the table.

This opens a window with a table of saved versions of the selected resource. New resources have only one version, the current version.

For each version, the table displays the following information:

• Version is the serial number of the resource version. When you save changes to the resource and create a new version, the serial number is increased by 1.

  The version with the highest number and the most recent publication date reflects the current state of the resource. Version 1 reflects the state of the resource at the moment when it was created.

• Published is the date and time when the resource version was created.
• Author is the login of the user that saved the changes to the resource.

  If the changes were made by the system or by the migration script, the displayed value is system.

• Comment is a text comment added by the author when saving changes, or a system comment describing the changes made.
• Retention period is the number of days and the date after which the resource version will be deleted.

  If necessary, you can configure the retention period for resource versions.

• Actions is the button that restores the resource version.

You can sort the table of resource versions by the Version, Published, and Author columns by clicking the heading and selecting Ascending or Descending. You can also display only changes made by a specific author or authors in the table by clicking the heading of the Author column and selecting the authors as needed.

If you want to view the status of a resource in a specific version, click that version in the table. This opens a window with the resource of the selected version, in which you can:

• View the settings specified in that version of the resource.
• Restore this version of the resource by clicking the Restore button.
• Export this version of the resource to a JSON file by clicking the Export button.

Comparing resource versions

You can compare any two versions of a resource, for example, if you need to track changes.

To compare versions of a resource:

1. In the KUMA Console, in the Resources section, select the type of resources that you need.

   This opens a window opens with a table of available resources of this type.

   If you want to view all resources, in the Resources section, go to the List tab.

2. Select the check box next to a resource and click the Show version history button in the upper part of the table.

   This opens the window with the version history of the resource.

3. Select the check boxes next to the two versions of the resource that you want to compare and click the Compare button in the upper part of the table.

This opens the resource version comparison window. Resource fields are displayed as a list or in JSON format. Differences between the two versions are highlighted. You can select other versions to compare using the drop-down lists above the resource fields.

Restoring a resource version

You can restore a previous version of a resource, for example, if you need to recover the resource in case of mistakes made when making changes.

Versions of automatically generated agents cannot be restored separately because they are created when the parent collector is modified. If you want to restore a version of an automatically generated agent, you need to restore the corresponding version of the parent collector.

To restore a previous version of a resource:

1. In the KUMA Console, in the Resources section, select the type of resources that you need.

   This opens a window opens with a table of available resources of this type.

   If you want to view all resources, in the Resources section, go to the List tab.

2. Select the check box next to a resource and click the Show version history button in the upper part of the table.

   This opens the window with the version history of the resource.

3. In the row of the relevant version, in the Action column, click the Restore button.

   You can also restore a version by clicking the row of this version and clicking the Restore button in the lower part of the window.

   You can restore only previous versions of a resource; for the current version, the Restore button is not available.

   If the structure of the resource has changed after a KUMA update, restoring its saved versions may not be possible.

4. Confirm the action and, if necessary, add a comment. If you do not add a comment, the "Restored from v.<number of the restored version>" comment is automatically added to the version.

The resource version is restored as a new version and become the current version.

If the resource for which you restored the version is added to the active service, this also changes the state of the service. You must restart the service to apply the resource change.

Configuring the retention period for resource versions

You can change the retention period of resource versions in the KUMA Console in the Settings → General section by changing the Resource history retention period, days setting.

The default setting is 30 days. If you want to keep all versions of resources without time limits, specify 0 (store indefinitely).

Only a user with the General administrator role can view and manage the retention period of resource versions.

The retention period of resource versions is checked daily, and versions of resources that have been stored in KUMA for longer than the specified period are automatically deleted. In the task manager, the Clear resource change history task is created to check the storage duration of resource versions and delete old versions. This task also runs after a restart of the Core component.

You can check the time remaining until a resource version is deleted in the table of versions, in the Retention period column.