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.
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 memory usage. For example, complex releases can take up to 2 GB of memory.
If you notice a drop in performance on your Release instance, try to increase the Java heap memory.
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:
- Go to Settings > General.
- 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
.zippackage 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.zippackage.
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.
The report header shows the timezone used for the dates and times in the report. Audit reports use the Release server timezone, not your personal display timezone, so that timestamps are consistent for all auditors.
Contents
The contents of the report are 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 happened while the task was running and why it failed or passed. You can see data for any of these five categories as a separate 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 the deployment in Deploy.
Each sheet contains a set of columns that can be grouped into three lists.
- Shared with other types of task-related sheets:
- Phase
- Task
- Type
- Status
- Start date
- End date
- Duration
- Assigned user
- Assigned team
- Completed by
- 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
- Unique to each type of task
Each type of task contains fields as follows:
- 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
- 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
- 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
- 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
- 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 user 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 was granted "edit task" permission for only 5 minutes before it was revoked, the report will still list that permission. The report does not specify the duration for which a user had a permission, only the fact that the user had the permission for some (or all) of the time while the release was in progress.
The Permissions report can reveal the source of a user's permission: for example, whether the user is a member of a folder team, or the user is a principal of a role and that role is a member of a team.
Only Release version 10.0.x is capable of keeping historical permission data. Release starts storing historical permission data only when you upgrade to 10.0.x for the first time. As a result, you can get valid data in your reports only 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 after the category that contains all tasks of that type in the release. Here is an example of a Security and Compliance sheet:
| Phase | Task | Type | Status | Start date | End date | Duration | Assigned user | Assigned team | Completed by | Server url | Server user | Project | Analysis date | Compliance check | Compliance data |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| New Phase | blackduck | BlackDuck: Check Compliance | Failed | June 13, 2019 11:37 AM | June 13, 2019 12:00 PM | 0d 0h 23m | https://blackduck.xebialabs.com | xebialabs | xebialabs_xl-deploy | June 12, 2019 06:03 PM | FAILED | License Risk: High: 18 Low: 0 Medium: 3 Operational Risk: High: 15 Low: 3 Medium: 17 Security Risk: High: 3 Low: 6 Medium: 3 |
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 to 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 a reference for the properties needed for each type of record:
| Type of record | Record category | Record properties |
|---|---|---|
| udm.BuildRecord | Build | serverUrl, serverUser, build, build_url, outcome, startDate, endDate, duration |
| udm.PlanRecord | Plan | serverUrl, serverUser, ticket, ticket_url, title, ticketType, status, updatedDate |
| udm.ItsmRecord | ITSM | serverUrl, serverUser, record, record_url, title, status, priority, createdBy |
| udm.CodeComplianceRecord | Security and Compliance | serverUrl, serverUser, project, project_url, analysisDate, outcome, complianceData |
| udm.DeploymentRecord | Deployment | serverUrl, serverUser, deploymentTask, deploymentTask_url, applicationName, environmentName, version, status |
| Record | Instantiate | Create |
|---|---|---|
| udm.BuildRecord | taskReportingApi.newBuildRecord() | taskReportingApi.addRecord(buildRecord, True) |
| udm.PlanRecord | taskReportingApi.newPlanRecord() | taskReportingApi.addRecord(planRecord, True) |
| udm.ItsmRecord | taskReportingApi.newItsmRecord() | taskReportingApi.addRecord(itsmRecord, True) |
| udm.CodeComplianceRecord | taskReportingApi.newCodeComplianceRecord() | taskReportingApi.addRecord(codeComplianceRecord, True) |
| udm.DeploymentRecord | taskReportingApi.newDeploymentRecord() | taskReportingApi.addRecord(deploymentRecord, True) |
The second argument of the addRecord function, applyTaskAttributes, means that if the user has created task attributes of the appropriate type as part of a release design, those attributes are honored and the data from these attributes 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 is 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 a reference for 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 for the type of each property.
Build
| Property name | Property kind | Required | Description |
|---|---|---|---|
| creationDate | DATE | true | Timestamp of when this record was created. This field is filled automatically by Release. |
| serverUrl | STRING | false | URL of the build server |
| serverUser | STRING | false | User used to access the build server |
| build | STRING | true | The ID of the build |
| build_url | STRING | true | Link to the build job |
| project | STRING | true | The project name |
| outcome | STRING | true | Result of the build |
| startDate | DATE | true | Start date of the build |
| endDate | DATE | true | End date of the build |
| duration | STRING | true | Duration of the build |
Plan
| Property name | Property kind | Required | Description |
|---|---|---|---|
| creationDate | DATE | true | Timestamp of when this record was created. This field is filled automatically by Release. |
| serverUrl | STRING | false | URL of the plan server |
| serverUser | STRING | false | User used to access the plan server |
| ticket | STRING | true | Ticket ID |
| ticket_url | STRING | true | Ticket URL |
| title | STRING | true | Issue title |
| ticketType | STRING | true | Ticket type |
| status | STRING | true | Status of the ticket |
| updatedDate | DATE | true | Date and time of last update |
| updatedBy | STRING | false | Person who performed the last update |
ITSM
| Property name | Property kind | Required | Description |
|---|---|---|---|
| creationDate | DATE | true | Timestamp of when this record was created. This field is filled automatically by Release. |
| serverUrl | STRING | false | URL of the ITSM server |
| serverUser | STRING | false | User used to access the ITSM server |
| record | STRING | true | Record number |
| record_url | STRING | true | Record URL |
| title | STRING | true | Record title |
| status | STRING | true | Status of the record |
| priority | STRING | true | Priority |
| createdBy | STRING | true | User who created the record |
CodeCompliance
| Property name | Property kind | Required | Description |
|---|---|---|---|
| creationDate | DATE | true | Timestamp of when this record was created. This field is filled automatically by Release. |
| serverUrl | STRING | false | URL of the code compliance server |
| serverUser | STRING | false | User used to access the code compliance server |
| project | STRING | true | Project |
| project_url | STRING | true | URL for the project |
| analysisDate | DATE | true | Date of the analysis |
| outcome | STRING | true | Result of the analysis |
| complianceData | STRING | true | Compliance data |
Deployment
| Property name | Property kind | Required | Description |
|---|---|---|---|
| creationDate | DATE | true | Timestamp of when this record was created. This field is filled automatically by Release. |
| serverUrl | STRING | false | URL of the deployment server |
| serverUser | STRING | false | User used to access the deployment server |
| deploymentTask | STRING | true | The deployment |
| deploymentTask_url | STRING | true | The URL of the deployment |
| applicationName | STRING | false | The name of the application whose version is being deployed |
| environmentName | STRING | false | The name of the environment where this task deploys to |
| version | STRING | false | The version of application |
| status | DeploymentStatus | true | The 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 than 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.