Skip to main content
Version: Release 22.2

Release Audit Report

This topic covers the audit report in Digital.ai Release, which provides full traceability and auditability for auditors. You can generate an audit report for releases that are in progress, completed, or archived.

For more information about how to generate the audit report, see Generate the audit report.

Note As a prerequisite, if you are using Release in cluster mode, you must have a shared directory specified in the xl-release.conf to store generated reports. See Cluster Mode for details on setting up Release in cluster mode.

Requirements​

Running multiple audit reports at the same time can increase the memory usage. For example, complex releases can take up to 2Gb of memory.

Tip: If you notice a drop in performance on your Release instance, try to increase the Java heap memory.

Recommended: If you are upgrading from a previous version to 9.0 or higher, you should also upgrade the following plugins to use the release audit report:

Note: By default, Jira and Jenkins are bundled with the installation package, and only need to be upgraded if the user installed them separately. If you use any other custom or community plugins, these should also be updated to take advantage of the release audit report.

Audit report permissions​

The global Auditor permission is required to generate and download the release audit reports.

For more information about permissions and how to add them, see Global permissions.

Store reports​

The generated audit reports are stored as temporary files on a shared file system. These reports are available for a default period of 10 days after they are generated. You cannot delete the reports manually from Release.

Set retention period​

To configure the retention period for the generated reports in Release:

  1. Go to Settings > General.
  2. Under Release audit reports, in the Delete release audit report older than field, specify the maximum number of days the reports can be stored before automatically deleting them.

Types of reports​

  • Single release - show all the information that happened in a release and additional data from tool integrations.
  • Multiple releases - a .zip package containing a master report and one audit report for each of your filtered releases. The master report is an excel file indexing all of the single release report files in a .zip package.

Format​

For a single release, you can export an excel file containing information about the release.

For multiple releases, you can download a .zip package containing multiple excel files with report information.

Contents​

The contents of the report is displayed in separate sheets in the .xls file based on the type of data gathered from Release and the existing integrations.

Information gathered from Release​

  • Release overview tab - Details about the release, including phases and tasks.

  • Task details tab - Input and output information from the tasks in the release.

  • Activity details tab - The activity log from Release.

Integrations data​

Plugin tasks provide additional information to help you understand what has happened while running the task and why the task failed or passed. You can see data for any of these five categories as a separated sheet in your report:

  • Plan tab - Shows the details for Jira tasks from Release including the Jira ticket number.

  • Build tab - Shows the details for Jenkins tasks from Release and accessible build URLs from Jenkins.

  • Security and Compliance tab - Shows the details for the SonarQube, SonarCloud, Fortify on Demand, and BlackDuck tasks including links to the corresponding projects.

  • ITSM tab - Shows the details for ServiceNow tasks from Release and an accessible link to the project in ServiceNow.

  • Deployments tab - Shows the details for Deploy tasks from Release and an accessible link to de the deployment in Deploy.

Each sheet contains a set of columns that can be grouped into three lists.

  1. Shared with other types of task related sheets:
    • Phase
    • Task
    • Type
    • Status
    • Start date
    • End date
    • Duration
    • Assigned user
    • Assigned team
    • Completed by
  2. Task specific:
    • Server url: Server base URL used to fetch data, not an object URL
    • Server user: Username used to authenticate to the server when fetching data
  3. Unique to each type of task

Each type of task contains fields as follows:

  1. Build (example: Jenkins)
    • Project: The name of the project
    • Build ID: The ID of the build
    • Build result: Result of the build
    • Build start: Start date of the build
    • Build end: End date of the build
    • Build duration: Duration of the build
  2. ITSM (example: ServiceNow)
    • Record number: Unique identifier in ITSM
    • Record title: Title of the record in ITSM
    • Status: Status of the record
    • Priority: Priority of the record
    • Record created by: Record created by
  3. Plan (example: Jira)
    • Ticket id: Ticket ID
    • Title: Issue title
    • Ticket type: Ticket type
    • Status: Status of the ticket
    • Updated on: Date and time of last update
    • Updated by: Person who performed the last update
  4. Security and Compliance (example: Sonarqube, SonarCloud, BlackDuck, Fortify, and Fortify on demand)
    • Project: The project name
    • Analysis date: Date of the analysis
    • Compliance check: Result of the analysis
    • Compliance data: The compliance data
  5. Deployment (example: Deploy)
    • Deployment task: The deployment task
    • Application: The Application name
    • Environment: The Environment name
    • Application version: The version of the application
    • Deployment status: The status of the deployment

Important: Only releases executed after 9.0.x will contain the audit report data.

User permissions data​

The "Permissions" sheet of the report contains permissions relevant to the release (folder or release specific), that each of users had between release start and end. For example, if the release started on a Monday and ended on a Wednesday, and on Tuesday user A have got "edit task" permission for 5 minutes only, and then permission was revoked, the report will still list that permission. Report will not specify duration for which user had permission, only the fact that user had permission for some (or all) time while release was in progress.

The Permission report can reveal the source of a user's permission - for example, whether user is a member of a folder team, or user is a principal of role and role is a member of a team.

Important: Only version 10.0.x is capable of keeping historical permission data. Note, that only when you upgrade to 10.0.x first time, Release will start storing historical permission data, and, as a result, you will only be able to get valid data in your reports for releases that happened after the date you upgraded to 10.0.x.

Example​

If your release contains tasks producing this type of data, you will see a separate sheet in your release audit report named with the category which contains all the tasks of that type in that release. Here is an example of a Security and Compliance sheet:

PhaseTaskTypeStatusStart dateEnd dateDurationAssigned userAssigned teamCompleted byServer urlServer userProjectAnalysis dateCompliance checkCompliance data
New PhaseblackduckBlackDuck: Check ComplianceFailedJune 13, 2019 11:37 AMJune 13, 2019 12:00 PM0d 0h 23mhttps://blackduck.xebialabs.comxebialabsxebialabs_xl-deployJune 12, 2019 06:03 PMFAILEDLicense Risk: High: 18 Low: 0 Medium: 3 Operational Risk: High: 15 Low: 3 Medium: 17 Security Risk: High: 3 Low: 6 Medium: 3
note

The columns Server url and Project contain hyperlinks that point to the server and the project URL on that server respectively.

The Project field which contains a hyperlink to the project is specific only for the Security and Compliance category. The same applies for Build id in the Build category, Record number in ITSM, and Ticket id in the Plan category.

Record data in custom plugins​

If you are using custom plugins and you want to record that data for the release audit report, you must modify your custom plugin. You can use the following table as reference of the properties needed for each type of record:

Type of recordRecord categoryRecord properties
udm.BuildRecordBuildserverUrl, serverUser, build, build_url,outcome, startDate, endDate, duration
udm.PlanRecordPlanserverUrl, serverUser, ticket, ticket_url, title, ticketType, status, updatedDate
udm.ItsmRecordITSMserverUrl, serverUser, record, record_url, title, status, priority, createdBy
udm.CodeComplianceRecordSecurity and ComplianceserverUrl, serverUser, project, project_url, analysisDate, outcome, complianceData
udm.DeploymentRecordDeploymentserverUrl, serverUser, deploymentTask, deploymentTask_url, applicationName, environmentName, version, status
RecordInstantiateCreate
udm.BuildRecordtaskReportingApi.newBuildRecord()taskReportingApi.addRecord(buildRecord, True)
udm.PlanRecordtaskReportingApi.newPlanRecord()taskReportingApi.addRecord(planRecord, True)
udm.ItsmRecordtaskReportingApi.newItsmRecord()taskReportingApi.addRecord(itsmRecord, True)
udm.CodeComplianceRecordtaskReportingApi.newCodeComplianceRecord()taskReportingApi.addRecord(codeComplianceRecord, True)
udm.DeploymentRecordtaskReportingApi.newDeploymentRecord()taskReportingApi.addRecord(deploymentRecord, True)
note

The second argument of addRecord function applyTaskAttributes means that, if the user has created task attributes of appropriate type, as part of a release design, those attributes will be honored and the data from these attributes will overwrite the data from the record submitted by your plugin. Digital.ai strongly encourages you to set this argument to True. If you set it to False, then your record will be saved unchanged, even if the user has configured attributes, which may be confusing.

If you are using custom plugins and you want to record that data for the release audit report, you must modify your custom plugin. You can use the following table as reference of the properties needed for each type of record:

Example: The user created an attribute of type 'Deployment', which specifies an 'Application' property set to 'MyApp' and an 'Environment' set to 'Dev1' on a xldeploy.XldTask. The task is then executed triggering a deployment in 'Deploy', where the 'Application' is actually named 'MyApp001' and the 'Environment' is 'Development1'. Since the xlr-xld-plugin calls the addRecord function with applyTaskAttributes set to true, the data for 'Application' and 'Environment' that will end up in the 'Audit Report' for this release is picked from the attribute and would be 'MyApp' and 'Dev1', and those fields are overwritten with this data in the ReportingRecord. If there was no attribute, the data from the record would be used ('MyApp001' and 'Development1').

To add a new row on the Build tab of the release audit report, add this code to your custom plugin:

myBuildRecord = taskReportingApi.newBuildRecord()
myBuildRecord.targetId = task.id

myBuildRecord.project = "My project"
myBuildRecord.build = "#768"
myBuildRecord.build_url = "https://build-ci.com/build/768"
myBuildRecord.serverUrl = "https://build-ci.com"
myBuildRecord.serverUser = "my user from build system"
myBuildRecord.outcome = "SUCCESS"
myBuildRecord.startDate = Date(...)
myBuildRecord.endDate = Date(...)
myBuildRecord.duration = "3h 2m"

taskReportingApi.addRecord(myBuildRecord, True)

Other attributes​

For other kinds of attributes, see the following references about the type of each property.

Build

Property nameProperty kindRequiredDescription
creationDateDATEtrueTimestamp of when this record was created. This field is filled automatically by Release.
serverUrlSTRINGfalseURL of the build server
serverUserSTRINGfalseUser used to access the build server
buildSTRINGtrueThe ID of the build
build_urlSTRINGtrueLink to the build job
projectSTRINGtrueThe project name
outcomeSTRINGtrueResult of the build
startDateDATEtrueStart date of the build
endDateDATEtrueEnd date of the build
durationSTRINGtrueDuration of the build

Plan

Property nameProperty kindRequiredDescription
creationDateDATEtrueTimestamp of when this record was created. This field is filled automatically by Release.
serverUrlSTRINGfalseURL of the plan server
serverUserSTRINGfalseUser used to access the plan server
ticketSTRINGtrueTicket ID
ticket_urlSTRINGtrueTicket URL
titleSTRINGtrueIssue title
ticketTypeSTRINGtrueTicket type
statusSTRINGtrueStatus of the ticket
updatedDateDATEtrueDate and time of last update
updatedBySTRINGfalsePerson who performed the last update

ITSM

Property nameProperty kindRequiredDescription
creationDateDATEtrueTimestamp of when this record was created. This field is filled automatically by Release.
serverUrlSTRINGfalseURL of the ITSM server
serverUserSTRINGfalseUser used to access the ITSM server
recordSTRINGtrueRecord number
record_urlSTRINGtrueRecord URL
titleSTRINGtrueRecord title
statusSTRINGtrueStatus of the record
prioritySTRINGtruePriority
createdBySTRINGtrueUser who created the record

CodeCompliance

Property nameProperty kindRequiredDescription
creationDateDATEtrueTimestamp of when this record was created. This field is filled automatically by Release.
serverUrlSTRINGfalseURL of the code compliance server
serverUserSTRINGfalseUser used to access the code compliance server
projectSTRINGtrueProject
project_urlSTRINGtrueURL for the project
analysisDateDATEtrueDate of the analysis
outcomeSTRINGtrueResult of the analysis
complianceDataSTRINGtrueCompliance data

Deployment

Property nameProperty kindRequiredDescription
creationDateDATEtrueTimestamp of when this record was created. This field is filled automatically by Release.
serverUrlSTRINGfalseURL of the deployment server
serverUserSTRINGfalseUser used to access the deployment server
deploymentTaskSTRINGtrueThe deployment
deploymentTask_urlSTRINGtrueThe URL of the deployment
applicationNameSTRINGfalseThe name of the application whose version is being deployed
environmentNameSTRINGfalseThe name of the environment where this task deploys to
versionSTRINGfalseThe version of application
statusDeploymentStatustrueThe status of the deployment

Configure reporting properties​

You can configure:

  • the maximum number of threads that can be used to generate reports at the same time
  • the folder location where the reports are stored
  • the interval you want to use to check if a report is older that the configured retention period and must be deleted

To configure these properties, add this code to XL_RELEASE_SERVER_HOME\conf\xl-release.conf:

xl {
    reporting {
        engine {
            maxThreadsCount = 10
            location = "reports"
            cleanUpInterval = 6 hours
        }
    }
}

Sample templates​

Templates that provide the release audit report are located in the Sample & Tutorials folder.