AIP Console Tools Jenkins Plugin

Purpose

This Jenkins Plugin allows you to automate some parts of using AIP Console, like delivering source code, running an application analysis or generating a snapshot through Jenkins.

Pre-Requisites

This plugin requires the following :

Jenkins version 2.60.3 or above
An installation of AIP Console that is accessible and configured.
An API Token for the user that will run the CLI (check here for details on obtaining a token)
The ability to generate an archive for your source code OR a configured location in AIP Console where your source will be saved/updated.

Installation (and Update)

To start using AIP Console Jenkins Plugin, you must first install the plugin in Jenkins.

To do this, you must go to Manage Plugins page of your Jenkins Server.

Then, in the "Advanced" tab, under "Upload Plugin", click "Browse" and select the aip-console-jenkins.hpi file.

Click on Upload and Jenkins should install the plugin.

Updating the plugin is the same process, but it might require to restart your Jenkins server after installation for the changes to take effect.

Configuration

To configure the AIP Console plugin, go to the "Configure System" page in the "Manage Jenkins" page.

On this page, go to the AIP Console global configuration section and enter the following required elements :

AIP Console URL : The URL to access the AIP Console server. Make sure that this address is accessible from the Jenkins Server and the Jenkins Node that might run the plugin as well.
API Key : The API key that will be used to authenticate to AIP Console.
Timeout : A global timeout setting in seconds before calls to AIP Console will be considered in error.
verbose : If it's checked then AIP Console log output will be display on screen. To hide major information keep this unchecked.

Using different AIP Console URL and API Key

In case the Job needs to target different AIP Console URL and use a different API Key, it's still possible. To do so, proceed as follows.

Create dedicated Job as describe in the next section
Expand the "Advanced Settings" section and fill fields with desired values.

Precedence rule

The value used for AIP Console URL and API Key is always coming from the Job itself when assigned.
If one field is not assigned then the one from the Global Configuration will be used.

Defining the Analysis Strategy using objectives options

These options can be updated when on-boarding a version using either

Add Version job
Deliver Version job.

The enabled options will be added to the existing default ones: Global Assessment and ** Function Points measurement**. To Enable/Disable Blueprint and Security assessment you will need to expand the Advanced Settings of the dedicated job.

Quick Start

Create Application

To create an application, add the Create application on AIP Console Step to a job.

In that build step,

you must provide the application name.
You also optionally have the possibility to decide whether the application should keep the delivered version history or not.

The application will be created on AIP Console after you've run the Jenkins Job.

Important note

When an application is created without the deliveries history then the source code should be located in the Source Folder Path sub-folders. This meant no file will not be accepted.

Add Version

The Add Application Version to AIP Console will create a new version of an application, run an analysis and create a snapshot of that analysis.

You can configure the step to optionally add the blueprint objective to the exising objectives.
To do so, check the following option checkbox in the "advanced settings" section
You can also configure the step to customize either the exclusion patterns or the project exclusion rules.
Please keep in mind that

The patterns list is comma separated items
When dealing with the following exclusion rules the jeeFileDiscoverer extension should be operating

When a snapshot is available, you can optionally decide whether to publish the application to the Health Dashboard or not.
You can choose the Module generation type you would like to generate
or just keep the default one that's available on CAST Console (use default).

This step requires the following :

An application name for which a new version will be created. This application must exist in AIP Console.
A path to a zip or tgz archive file to upload (NOTE: you can also provide a folder path; more details in the Advanced Usage Section below).

This step will perform the following actions :

Upload the file source.zip to application my app
Create a new version with an automatically generated name
Run an analysis on this version
Create a snapshot

This version and the snapshot can be found in the Application's page in AIP Console.

Deliver

The Deliver Source Code to AIP Console step is similar to the Add version step above.

You can configure the step to optionaly add the blueprint objective to the exising objectives.
To do so, check the following option checkbox in the "advanced settings" section
You can configure the step to optionally add the blueprint objective to the exising objectives.
To do so, check the following option checkbox in the "advanced settings" section
You can also configure the step to customize either the exclusion patterns or the project exclusion rules.
Please keep in mind that

The patterns list is comma separated items
When dealing with the following exclusion rules the jeeFileDiscoverer extension should be operating

It requires the following :

An application name for which a new version will be created. This application must exist in AIP Console.
A path to a zip or tgz archive file to upload (NOTE: you can also provide a folder path; more details in the Advanced Usage Section below).
Whether the version should be current or not

This step will perform the following actions :

Upload the file source.zip to application my app
Create a new version with an automatically generated name

The version will be created and visible inside the Versions tab of the application in AIP Console.

Analyze

The step Analyze Application on AIP Console will only run an Application Analysis on AIP Console.

It only requires an Application Name.

But it stills some option that you can set

You can choose the Module generation type you would like to generate
or just keep the default one that's available on CAST Console (use default).

However, note that you need at least one Delivered version on AIP Console for this step to work correctly.

This step will perform the following actions :

Get the latest version
Start an analysis on that version

Snapshot

The step Create Snapshot on AIP Console will create a snapshot for an Application on AIP Console.

It only requires an Application Name.

However, note that you need to have run an Analysis on the Current version for the target Application.

This step will perform the following actions :

Create a Snapshot
Generate Snapshot Indicators
Optionally decided whether to publish the application to the Health Dashboard or not.

The Snapshot can then be found inside the Snapshot tab in AIP Console.

Advanced Usage

The quick start only covers the basic usage of each step of the plugin. The following sections provide greater details on what each parameters changes in the behavior of the AIP Console Tools plugin.

A Note on variable expansion

Variable expansion means replacing some variables in text fields to an environment variable value.

For example, creating an application with name "${JOB_NAME} (jenkins)", the Plugin will replace '${JOB_NAME}' with the name of the current running job. You can use these environment variables on the following fields in each jobs (when defined):

Application name
Version name
Snapshot name
Node name

You can manually add environment variables to a build or use global jenkins environment variables (see the jenkins documentation)