5.1.2.2. Projects

This section is about the connection between axivion_ci and the Dashboard, i.e. how analysis results are made available inside the Dashboard via artifacts. Please refer to Project Configuration about information on how to create these artifacts.

Dashboard Project configuration is done on the “Projects” page, see The project list configuration view, from within the Dashboard. You require the Configure Dashboard permission, in order to see the navigation entry in the navigation bar’s settings menu.

The project list configuration view

The project list configuration view

Project Artifacts

Artifacts are files containing analysis results and annotations. There are currently five types:

The first four artifacts are created by axivion_ci while the .dbx is created by the Dashboard.

Note

Mirror repositories needed by some Version Control Systems in order for the Dashboard to be able to display source code are not considered artifacts in this context, as they are very often shared between several projects.

Project Types

There are two types of projects that only differ in the way their so-called artifacts are managed / installed to the Dashboard. From a usage point-of-view the two project types are completely identical. The Dashboard can handle a mixture of projects of both types at the same time. The types are:

  • Manually managed (default) – Artifacts are managed in filesystem by an administrator and typically reside on a network fileshare when axivion_ci and Dashboard run on different hosts

  • Automatically managed – This was introduced with 7.6.0 and basically eliminates the need for manual artifact management and installation. See here and here for reading about how to enable the feature and its current limitations

Projects with database mode “shared database”

Projects with database_mode configured to shared_database are found in server-side directories that can be configured in the lower list of added directories. Files with the suffix .db inside these directories will be shown inside the same list. They can be activated using the Install button and will be assigned a name derived from the analysis project that created them.

To deactivate such projects the Remove button can be used. While for such projects this will simply unregister the artifacts from the dashboard configuration (and you still have to manually delete it in the file system), for managed_upload projects it will delete them from the disk permanently. Whether the artifacts of a project are shared_database or managed_upload is indicated by the Managed column of the upper projects list.

Projects in database directories which are watched are installed and uninstalled automatically. The directories are scanned for new or removed database files when the dashboard server starts and when the watch status is set. While the server runs the watched directories are constantly watched for new and removed projects. Manually uninstalling projects whose databases are in a watched directory is forbidden.

The directory watching is registered at the start of the Dashboard or when the directory is configured to be a watched directory. When the directory does not exist at that time, it will not be watched - even when it is created later on. After the registration of a directory, its path becomes irrelevant: the registration only uses the directory handle/inode. So when a watched directory is renamed/moved, it will still be watched. Only on Dashboard restart or un-watching/re-watching the directory, the configured directory path comes into play.

Projects with database mode “managed upload”

Projects with database_mode configured to managed_upload were introduced with 7.6.0 and basically eliminate the need for manual artifact management and installation as it is necessary for shared_database projects. See here for reading about how to enable the feature and its current limitations.

To delete such projects the Remove button can be used. While for automatically managed projects this will delete the artifacts from the disk permanently, for shared_database projects it will simply unregister them from the dashboard configuration. Whether the artifacts of a project are managed_upload or shared_database is indicated by the Managed column of the upper projects list.

All artifacts of automatically managed projects reside in one, non-configurable, dedicated folder called artifacts inside the Dashboard configuration folder.

Caution

Please do not manually work with the files inside the artifacts folder. If you are tempted to manually work with the files in this folder, it is likely you are in one of the use-cases not yet supported by this feature.

axivion_ci Authentication

In order for axivion_ci to have the permission to download and upload project artifacts we recommend the following steps:

Create an authentication token:

  • In the Dashboard Server: Create a dedicated user (e.g., builduser) for automation tasks (if you haven’t done so already).

  • Give that user the permissions Log In and Update Analysis Artifacts.

  • Go to the user’s personal page (click on its name in user-management).

  • Create an authentication token of type Continuous Integration and give it a useful description. For example: builduser token used by axivion_ci to access the Dashboard stored in our automation server.

Configure the Token in your Automation Server:

  • Automation systems usually have methods for storing credentials that you should use to store the username and token.

  • Configure your automation system such that the environment variable AXIVION_USERNAME is set to the username and AXIVION_PASSWORD to the token when axivion_ci is invoked.

  • Depending on your security requirements there are simpler but less secure methods for passing the credentials to axivion_ci.

In the Automation-Server Jenkins, this could look like the following:

Jenkins Credentials Configuration

Jenkins Credentials Storage Example

Applying the credentials in the Jenkins Automation Server in a groovy pipeline script could look like the following:

withCredentials([usernamePassword(
        credentialsId: 'dashboard-api',
        usernameVariable: 'AXIVION_USERNAME',
        passwordVariable: 'AXIVION_PASSWORD',
)]) {
    bat """
        set "BAUHAUS_CONFIG=%CD%\\Axivion"
        axivion_ci
    """
}

Classic Jenkins-Jobs can achieve the same via UI configuration.

List of Active Projects

In the upper list you can configure your active projects or remove them again. By selecting one or more projects and then clicking the Edit button a new window opens which shows you all configuration options possible for the selected set of projects.

Caution

If you change a project name you have to adjust the projectname input in your analysis configuration accordingly so the Continuous Integration can refer to the project correctly, e.g. when triggering Erosion Notification Emails

Note

Quite some aspects in the dashboard can be configured on a project group basis using *-patterns. So consider grouping your projects by giving similar projects similar prefixes or suffixes

If the Dashboard integrated Erosion Notification System is enabled, you will see the column Erosion Emails. It allows you to disable notifications on a per-project basis.

Enable Issue Annotations is another configurable column where you explicitly disable the Issue Annotations Feature. Consider doing this for preventing users from putting work in commenting and annotating issues that you will later throw away because you are still experimenting with your setup.

The Managed column indicates whether the artifacts of a project are shared_database or managed_upload.

The Version column gives you a hint on what internal schema version a database is at. The analysis data schema version numbers are different from the Axivion Suite version numbers.

Caution

Although you can migrate databases to newer versions explicitly via cidbman migrate we recommend doing this only for historical databases where there is no Continuous Integration running any more because the Axivion Suite version used for analyzing might be older than the Axivion Suite version used for running the dashboard. Analysis runs will automatically upgrade the schema version and it is best to leave this task to them.

The project list gives you further possibilities you usually don’t need like clearing cached data for the project in order to refresh the version list or updating the version control system cache. If the dashboard is running during analysis and properly known to the Continuous Integration, the cache updates will happen automatically.

Project Hierarchies

You can define hierarchies of projects for the Dashboard Page by naming them accordingly. The project name has to be prefixed with the groups it belongs to separated by one of the characters configured via the option Project Name Separators in General Settings (underscore (_), hyphen (-), and dot (.) by default). For example the projects TeamA-ProjectX-master and TeamA-ProjectX-feature will create a tree with the root TeamA that contains the group ProjectX that in turn contains the projects master and feature.

Note

A group cannot be a project, i.e. a project name must not be a prefix of another one. A group name must not be empty, i.e. separators must not be leading or trailing or occur consecutively.