IKAN ALM Reports Windows Installation Guide

Purpose

IKAN ALM Reports has been created as a complement to IKAN ALM, IKAN’s Application Lifecycle Management tool. With ALM Reports, IKAN ALM customers can run high-quality, highly configurable reports, thus extract important information from the IKAN ALM database which is not readily available from the IKAN ALM GUI.

This guide describes the procedure to install IKAN ALM Reports on Microsoft Windows. ALM Reports was created using the JasperSoft tools iReport and JasperReports Server. The ALM Reports installation procedure includes the installation of a bundled JasperReports Server (JRS).

Since ALM Reports runs reports from an IKAN ALM database, an IKAN ALM instance must first have been installed, or access to an IKAN ALM database must be available.

Prerequisites

Java 11

You will need a Java 11 64-bit vm to install and run ALM Reports. ALM Reports has been tested with Oracle Java, Adoptium Eclipse Temurin (formerly AdoptOpenJDK), Azul Zulu Builds of OpenJDK and OpenJDK on several Linux distros. Oracle Java can be obtained from Oracle’s website for non-production environments using an Oracle account. Adoptium OpenJDK can be obtained from https://adoptium.net and Azul Zulu Builds of the OpenJDK from https://azul.com/downloads/?package=jdk.

IKAN ALM

An IKAN ALM instance must have been installed prior to installing ALM Reports, or an IKAN ALM database must be available.

IKAN ALM Reports 5.9 is compatible with the database schema of IKAN ALM 5.9.

Java EE Application Server (Tomcat)

ALM Reports installs a Jasper Reports Server (JRS), and JRS needs a Java EE application server to run. The installation procedure of ALM Reports only supports Apache Tomcat 9 as valid application servers.

Database

ALM Reports supports MySQL, MsSQL, Oracle, and PostgreSQL as the database server for the IKAN ALM database.

The installation procedure of ALM Reports only supports MySQL and Microsoft SQL Server as the JasperReports Server database.

Installing IKAN ALM Reports

This chapter describes the installation procedure for IKAN ALM Reports.

  1. Unzip the delivered ALM_Reports5.9.zip to a folder of your choice. We will refer to this directory as <ALMREP-install>.

  2. Next, edit the install.properties file and set the properties needed by the installer.

    Please use a '/' in paths as ANT does not support '\'.

    The following properties are available:

    Property Explanation

    js.home

    Location where Jasper Server is to be installed. This property is required.

    appserver.home

    Home directory of the Application Server, for example the installation directory of an Apache Tomcat server.

    This property is required.

    The default value contains a suggested path to a Tomcat instance.

    appserver.http.port

    HTTP port of the Application Server.

    This property is required.

    The default value is "8080".

    appserver.service.name

    In case the Application Server is installed as a Windows service, specify the name of the service.

    During the installation process, the ALM Reports installer will try to stop and start the Application Server before installation. If this property is set, it will try to stop and start the service with the specified name. If the property is left empty, it will try to stop and start the Application Server using scripts.

    This property is optional, by default it is empty.

    jrs.db.type

    Jasper Server database type. Valid values are "mysql" and "sqlserver".

    This property is required.

    The default value is "mysql".

    jrs.db.host

    Host name or IP address of the Jasper Server database.

    This property is required.

    The default value is "localhost".

    jrs.db.port

    Port number of the Jasper Server database.

    This property is required.

    The default value is "3306".

    jrs.db.user

    User name to connect to the Jasper Server database.

    This property is required.

    The default value is "root".

    jrs.db.password

    Password of the user that will be used to connect to the Jasper Server database.

    This property is optional.

    The default value is "alm".

    jrs.db.name

    Database name of the Jasper Server database.

    This property is required.

    The default value is "jasperserver".

    quartz.mail.sender.host

    Scheduled Reports mail notification setting. Hostname of the mail server.

    Default value is "mail.localhost.com".

    quartz.mail.sender.username

    Scheduled Reports mail notification setting. User name to connect to the mail server.

    Default value is "admin".

    quartz.mail.sender.password

    Scheduled Reports mail notification setting. Password to connect to the mail server.

    Default value is "password".

    quartz.mail.sender.from

    Scheduled Reports mail notification setting. From address used in the mail notifications.

    Default value is "admin@localhost.com".

    quartz.mail.sender.protocol

    Scheduled Reports mail notification setting. Mail protocol used for the mail notifications.

    Default value is "smtp".

    quartz.mail.sender.port

    Scheduled Reports mail notification setting. TCP port to connect to the mail server.

    Default value is "25".

    quartz.mail.smtp.auth

    Scheduled Reports mail notification setting. Whether or not to use authentication to connect to the mail server.

    Default value is "false".

    alm.jaas.config.location

    Location of the jaas.config file used by IKAN ALM for its authentication.

    ALM Reports uses the settings of IKAN ALM for authenticating users. Therefore, it needs the location of IKAN ALM’s jaas.config file. Normally, this file is located in the folder <ALM_HOME>/system/security.

    This property is required.

    The default value contains a suggested path to a jaas.config file.

    alm.server.rdbms.type

    IKAN ALM database type.

    Valid values are MYSQL,MSSQL,ORACLE,DB2,POSTGRESQL.

    This property is required.

    The default value is "MYSQL".

    alm.server.rdbms.server

    Host name or IP address of the IKAN ALM database.

    This property is required.

    The default value is "localhost".

    alm.server.rdbms.port

    Port number of the IKAN ALM database.

    This property is required.

    The default value is "3306".

    alm.server.rdbms.user

    User name to connect to the IKAN ALM database.

    This property is required.

    The default value is "root".

    alm.server.rdbms.pwd

    Password of the user that will be used to connect to the IKAN ALM database.

    This property is optional.

    The default value is "alm".

    alm.server.rdbms.dbname

    Database name of the IKAN ALM database.

    This property is required.

    The default value is "alm".

    alm.server.rdbms.dbschema

    Database schema name of the IKAN ALM database. Only relevant when using IBM DB2 or POSTGRESQL.

    This property is optional.

    The default value is "alm".

  3. The installation procedure doesn’t create the JRS database (specified in jrs.db.name). You must manually create this database before running the installer.

  4. Next, open a console window and run the install.cmd file to start the ALM Reports installation.

    Normally, it should detect your Java runtime. If it doesn’t, you need to edit the “setenv.bat” file and manually set the JAVA_HOME variable. You can also set specific Java options, like for example:

       SET JAVA_HOME=C:\java11
   SET JAVA_OPTS=-Xmx256m

    When installing, if your Application Server is running as a Windows Service, you must launch the install.cmd command with Administrative privileges (run as Administrator). If not, you may see an "Access denied" error message when the install script tries to stop the Windows Service of the Application Server and the ALM Reports installation will abort.

    During the install, you may be asked to grant administrative privileges (Windows User Account Control) to the installation process.

  5. The installer will execute the following operations:

    • Install a customized Jasper Reports Server

    • Start your Application Server

    • Deploy the ALM Reports

    • Stop your Application Server

  6. When the installation is successful, the following message is displayed:

    fig4 1

  7. Verify whether ALM Reports has been successfully installed.

    Start the Application server, and browse to the Jasper Server web-application.

    If you used the default settings, this means opening the URL "http://localhost:8080/jasperserver".

    fig4 2

  8. Log in with the user/password combination of a valid IKAN ALM user (the authentication of IKAN ALM and ALM Reports are linked, they use the same jaas.config file).

  9. Verify that a resource folder named “IKANALM” exists and has the following structure:

    almrep fig2

  10. IKAN ALM Reports is now installed and ready to be used!

Using IKAN ALM Reports

In this chapter, we will give a short description of each of the available reports. Please note that by default all reports have to be run manually, no reports have been scheduled to run automatically. To set this up, consult the JasperReports Server documentation.

Approvals Overview

Reports the latest Approvals issued by IKAN ALM.

The User can limit the result in various ways, for example by specifying the User that approved or rejected an approval, setting a Project or Package name, or the approval status.

Compare Package Activity on 2 Levels

Reports the latest Level Requests of selected Packages of a Project, clearly showing the differences between 2 selected Levels.

The User must select a Project and 2 Levels for this report to return any results.

Environment Parameter Inventory

Reports all defined Build and Deploy parameters. The result can be limited in various ways, for example by setting the Parameter name, the Project name, the Level name, or the Environment name.

Global Admin Overview

Reports the configuration of the Global Administration of IKAN ALM.

The User can select which parts of the Global Administration configurations he/she wishes to see in the report. For example, the User can select to report all defined Machines, Transporters, and VCRs.

Issue Activity

Reports information of an Issue and the latest Level Requests performed by IKAN ALM that are related to the Issue.

The User must provide an Issue ID for this report to return any results. The result can be limited in various ways, for example by setting the Project name, the Level type, or the Level name.

Level Request Detail Overview

Reports detailed information about 1 specific Level Request performed by IKAN ALM. The User must specify the OID of a Level Request for this report to return any results.

The User can optionally select which pieces of information he/she wishes to see in the report.

Level Requests Overview

Reports the latest Level Requests performed by IKAN ALM.

The User can limit the result in various ways, for example by setting a Project name, one or more Level Request statuses, or the type of a Level.

Machine Activity

Reports the latest Builds and Deploys that were executed on a specific Machine.

The User must select a Machine for this report to return any results. The result can be limited in various ways, for example by setting the Project name, the Level type, or by specifying one or more Build or Deploy statuses.

Package Overview

Reports information of a Package and the latest Level Request per Level, allowing a User to easily see which build of the Package is currently active on each Level. Optionally reports all Level Requests related to the Package, and the files that are contained in the Package.

The User must select a Project name and a Package for this report to return any results.

Phase Parameters Overview

Reports all the Parameters that are defined for a specific IKAN ALM Phase, in which Levels and Environments the Parameters are used, and their values in each of those Environments.

The User must select a Phase name for this report to return any results.

Phases Overview

Reports information on the Phases defined in IKAN ALM.

The result can be limited in various ways, for example by selecting the Name, Version, or Author.

Optionally, it reports the Phase’s Parameters.

Project Activity

Reports the overall status of a Project by reporting the latest successful Level Requests of a Project per Project Stream and per Package.

The User must select a Project for this report to return any results. The result can be limited in various ways, for example by selecting specific Project Streams and/or Packages.

Project Configuration

Reports the configuration of a specific IKAN ALM Project.

The User can select which parts of the Project configuration he/she wishes to see in the report. For example, the User can select to report all defined Project Streams, Life Cycles, and Levels of a Project. The User must select a Project for this report to return any results.

File Revision Activity

Reports the Packages that contain the specified file in the specified path. The User must specify a filename for this report to return any results. The result can be limited in various ways, for example by selecting the Revision, Project name, or Package name.

Optionally also reports the Level Requests of the Packages.

Uninstalling ALM Reports

The procedure to uninstall ALM Reports is similar to the installation procedure: you adapt the install.properties, and then run the uninstaller.

The uninstaller uses the same properties file as the installer, so if you kept the installation folder you can just launch uninstall.cmd and ALM Reports will be uninstalled. If you didn’t keep the installation folder, you must again edit the install.properties and set the values according to your current installation of ALM Reports. Please refer to Installing IKAN ALM Reports for a detailed explanation of all the available properties.

The uninstaller will execute the following operations:

  • Stop the application server

  • Delete the Jasper Server web-application

  • Delete the Jasper Server installation folder

To start the uninstaller, open a console and run the uninstall.cmd file. Normally, it will detect your Java runtime. If it doesn’t, you need to edit the “setenv.bat” file and manually set the JAVA_HOME variable.

If the uninstall process is successful, the following message is displayed:

fig6 1

Troubleshooting

Can’t connect to the IKAN ALM database

Opening a report fails and an error similar to the one below is displayed:

almrep fig3

Solution

Check whether the IKANALM Data Source is configured correctly.

  1. Browse to root > IKANALM > Data Sources.

  2. Click on the IKANALM MYSQL Data Source, and click Edit.

    almrep fig4

  3. Verify the connection parameters.

  4. Test the connection by clicking the Test Connection button at the bottom of the page.