Release audit report

You can generate an audit report for all the releases executed through XL Release, detailing full traceability and auditability to deliver to the 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.

Requirements

  • If you are using XL Release in cluster mode, you must specify a shared drive to store generated reports.
  • Running multiple audit reports at the same time can increase the memory usage. For example, complex releases can take up to 2Gb of memory. If you notice performance slowness on your XL Release instance, try to increase the Java heap memory.

Note: 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:

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 XL Release.

Set retention period

To configure the retention period for the generated reports in XL 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 XL Release and the existing integrations.

Information gathered from XL 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 XL Release.

Integrations data

Plugin tasks that 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 XL Release including the Jira ticket number.

  • Build tab - Shows the details for Jenkins tasks from XL 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 XL Release and an accessible link to the project in ServiceNow.

  • Deployments tab - Shows the details for XL Deploy tasks from XL Release and an accessible link to de the deployment in XL 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 enlisted:

  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 (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

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

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:

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

Note: The columns Server url and Project contain hyperlinks pointed 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 attribute:

Type of attribute Attribute category Attribute properties
udm.BuildFacet Build serverUrl, serverUser, build, build_url,outcome, startDate, endDate, duration
udm.PlanFacet Plan serverUrl, serverUser, ticket, ticket_url, title, ticketType, status, updatedDate
udm.ItsmFacet ITSM serverUrl, serverUser, record, record_url, title, status, priority, createdBy
udm.CodeComplianceFacet Security and Compliance serverUrl, serverUser, project, project_url, analysisDate, outcome, complianceData

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

myFacet = myFacetApi.newFacet("udm.BuildFacet")
myFacet.targetId = task.id

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

facetApi.createFacet(myFacet)

Other attributes

For other kinds of attributes, see the following references about 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 XL 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 XL 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 XL 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 XL Release.
serverUrl STRING false URL of the ITSM server
serverUser STRING false User used to access the ITSM 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

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 the 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 Sample & Tutorials folder.