Creating Revision Reports

As a system administrator, you seek to maintain a secure, compliant, and well-managed automation environment. Revision Reports are a critical tool to achieve that goal, as they are designed to create chronologically structured reports that capture the history of changes within your Automic Automation Client or Clients.

This page includes the following:

Overview of Revision Reports

The Revision Reports log a wide array of activities, providing a detailed audit trail of modifications, deletions, imported and transported objects and other significant activities:

  • Auditing and Compliance

    Revision Reports are essential because they provide a clear record of who made what changes and when, aiding in compliance with internal policies and external regulations.

  • Tracking System Changes

    Revision Reports allow you to track user inputs and changes to the system when objects are modified, imported, or deleted. This can be invaluable for troubleshooting issues, understanding system behavior, and identifying potential security risks.

  • Maintaining Data Integrity

    By closely monitoring changes, you can ensure the integrity of your environment(s) by promptly identifying and addressing any unauthorized or erroneous modifications.

Important!

  • If you have logging for revision reports activated in a Client, you cannot add or remove users from a user group. In this case, you can directly add or remove them in the User object.

  • Activating logging for the revision report automatically activates Version Management, which is required when you compare objects and cannot be deactivated. For more information, see Defining the Version Management Page.

  • You can use the AE DB Reorg utility to reorganize revised data. For more information, see Object Audit Tab.

  • If you do not use the AE DB Revision Report utility regularly and your data is not revised, make sure that you set the OBJECT_AUDIT key of the UC_UTILITY_REORG variable to FALSE as otherwise your data is reorganized when you run the AE DB Reorg utility, see UC_UTILITY_REORG - Reorganization Specifications.

Important! Follow the database maintenance workflow described here: Database Maintenance Flow.

How to Create Revision Reports

You can create Revision Reports using the following methods:

The process results in a ZIP file that contains the relevant revision reports. This package is stored in a default location as soon as the reports are created. You can then move those files to a directory of your choice. The default store location is the following directory, depending on the method you used to create your revision reports:

Prerequisites for Creating Revision Reports

Make sure that you meet the following prerequisites:

  • You need the Database Maintenance (DB_MAINTENANCE) privilege to trigger and the Access to metrics and download audit reports (ACCESS_METRICS_ENDPOINT) privilege to download Revision Reports. For more information, see Granting Automation Engine Privileges.

  • To activate object logging, set the OBJECT_AUDIT key of the variable in UC_CLIENT_SETTINGS to Y, see OBJECT_AUDIT.

  • Set the SECURITY Parameters in UC_CLIENT_SETTINGS to log authorized/denied accesses, see SECURITY Parameters.

Monitored and Logged Activities

Automic Automation monitors the following activities and saves it per Client or Clients in the Revision Reports:

Important! To ensure that Accesses of any kind and User logons are monitored and logged to the database, you must activate the SECURITY_AUDIT_FAILURE and SECURITY_AUDIT_SUCCESS keys in the UC_CLIENT_SETTINGS variable. Note that to capture User login times, the LOGON value must be explicitly included in these security keys. User logoffs, however, are captured automatically regardless of this setting. For more information, see SECURITY Parameters.

  • Objects that are created or renamed

    The details of objects that were created or renamed

  • Objects that are moved

    The source and target folder of the objects that were moved

  • Imported and transported objects

    Import and transportation times. Contents of the XML file and the transport files are not included in the revision report.

  • Task starts and restarts

    The start time which is the activation time

  • Modifications at runtime

    Changes made through monitors or concerning states, for example. Modified JCL is not written to the revision report. You can find it in the object report.

  • Tasks that abnormally

    Tasks that show an abnormal end

  • Objects that are deleted or restored

    The details of objects that were deleted or restored

  • Object modifications

    Changes of object definitions such as changed priorities or start types. The revision report includes the old and the new values in that it includes the part of the XML structure of the object that includes the changed attribute.

    The following exceptions are not logged:

    • Changes that are made by using the AE script elements

    • Status changes of Sync objects

    • Contents of Variable objects,

    • Changes of Calendar objects

  • Accesses of any kind

    Access attempts to objects and folders, regardless of whether they are successful or represent access violations because of missing AE authorizations.

  • User Logon/Logoff

    The times users log on to the system or off

Creating Revision Reports through AWI

You trigger the Revision Report process for one or more Clients from the list of Clients, either in Client 0 or in a production Client. As soon as the Revision Report run starts, an entry is written to the Client History list displaying its runID, its status and additional information such as name, type (which is always CLNREVR for these operations), and so forth. Once the report has been created , you can download the resulting file.

Make sure you meet all the prerequisites required before creating Revision Reports, see Prerequisites for Creating Revision Reports

To run the Start Revision Report function, do the following:

  1. Go to the Administration perspective and open the list of Clients.

  2. Select the Client or Clients for which you want to create Revision Reports. If you are working in a production Client, this list contains only one entry. In Client 0 it contains multiple entries.

  3. Right-click and select Database Maintenance > Start Revision Report. A dialog is displayed that shows you either the Client or number of Clients for which you want to create the report. It also prompts you to refine the parameters of the Revision Report:

    1. Define a date and time range (From - Until) for the report.

    2. Optionally, select the Update Archived checkbox to set archive flags to the data included in the report. This is relevant for future reports in case you want to only include data that was never included in a report before.

    3. Optionally, select Include Not Archived Only checkbox to include only modification entries that have never been included in a revision report before such as entries that do not have archive flags.

    4. Optionally, define the Type of content that you want to be included in the report:

      • ACCESS - Unauthorized access

      • CANCEL - Tasks aborted

      • CREATE - New objects created

      • DELETE - Objects deleted

      • IMPORT - Objects imported

      • MOVE - Objects moved

      • OBJ_MOD - Object modifications

      • RENAME - Objects renamed

      • RESTART - Tasks restarted

      • RESTORE - Objects restored

      • RUN_MOD - Objects modified at runtime

      • START - Tasks started

      • TRNSPRT - Objects transported

      • USER - Successful user logons and logoffs

      If you do not select any type, all options are included.

    5. Click Start or Cancel the Revision Report.

  4. The reports are then available on the Client History page. Right click the relevant entry an select Download Revision Report. For more information, see Monitoring the Client History.

  5. The zip file containing the revision reports is now available in the directory that you have specified as default download folder in your browser.

You can see the list of all your runs on the Client History page. For more information, see Monitoring the Client History.

Creating Revision Reports Using the AE REST API

You use the REST API to create revision reports in on-premises, AAKE and Automic SaaS environments. Depending on your type of environment, the procedure is slightly different:

  1. Regardless of the environment in which you are, make sure that you meet the necessary requirements, see Prerequisites for Creating Revision Reports

  2. Define where the resulting revision report should be stored by default:

    • On-premises environments: the outputPath parameter in the Automation Engine INI file

    • AAKE / Automic SaaS: the pvc in the values.yaml file

  3. Trigger the report creation process.

  4. Download the files from the default location to a directory of your choice. You do this from your REST API client.

For more information, see REST API: Creating Revision Reports.

Revision Reports Recommendations and Best Practices

Consider the following issues when creating Revision Reports:

  • Schedule the generation of revision reports on a regular basis. This proactive approach ensures that you consistently capture changes and maintain an up-to-date audit trail.

  • Integrate the Revision Report generation with your scheduled maintenance procedures (archiving, reorganizing, unloading). This coordinated approach ensures that your database remains healthy and efficient.

  • Consider generating revision reports before implementing major system changes or upgrades. This provides a baseline for comparison and facilitates easier troubleshooting if issues arise.

  • In the event of a system incident or security breach, revision reports can be invaluable for understanding what happened, identifying the root cause, and implementing corrective actions.

See also: