LeanIX Value Stream Management

We will deprecate this plugin effective 25.8.2023 . The legacy VSM product that this plugin supports is not being sold anymore and is in best-effort maintenance stage. The new product offering can be found here. Please make sure you migrate your workloads to the new VSM product.

This plugin connects Jenkins Jobs with your LeanIX workspace. When the plugin is integrated in your Jenkins pipelines and jobs, information on your services built and deployed with Jenkins can be called up in LeanIX fact sheets .

• The LeanIX Value Stream Management plugin must be installed: https://www.jenkins.io/doc/book/managing/plugins/
• You have a valid LeanIX API token.
• If you are using scripted pipelines in which the LeanIX plugin is to be integrated as a step, the "Credentials Binding" plugin must be installed: https://plugins.jenkins.io/credentials-binding/. It is assumed user already installed pipeline plugin.
  For projects such as a Freestyle project, in which the plugin can be added via UI as a build step, the plugin for injecting environment variables might be required instead: https://plugins.jenkins.io/envinject/
• An SCM provider (e.g. Git) must be configured for the pipeline to be used and the possibly necessary plug-in installed.
• The manifest file made available by LeanIX and filled with the appropriate values is located in the corresponding repository, so that it can be accessed by the plugin. The contents is sent by the plugin to the LeanIX interface.
• If you manage npm projects in Jenkins, please install the npm license-checker ( https://www.npmjs.com/package/license-checker ). The plug-in will also initiate the installation, but this may fail for reasons of access rights.

• Setting up secrets in the Jenkins administration,
• Central configuration of the plugin,
• Configuration of individual pipelines and jobs in which the plugin is to be used.

• Scope: It is best to select "global", unless security reasons or company guidelines speak against it.
• Username: The host and thus the part of a URL that specifies the region of the LeanIX service in which the workspace is located, to which the data extracted by the plugin is to be sent.
• Password: A valid API token for the LeanIX workspace that matches the host.
• ID: "LEANIX_CREDENTIALS" is suggested here, but any valid variable name can be selected. It just needs to be used accordingly in the pipeline.
• Description: It is suggested to add a description here, so user can differentiate the credentials when using credentials binding plugin.

When you call this up, you will find two areas in which settings can be made.

1. In the uppermost area with the title "Pipeline Configuration in JSON format" there is an input field in which configurations in JSON format can be inserted. The structure of these configurations is as follows:

• "leanIXConfigurations" contains all configurations, root of the file
• "deploymentStageVarName": If you use environment variables for the configuration of the stage that your Jenkins job belongs to (e.g. test, production) you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the stage. The stage value can also be set in the local configurations of the jobs.
• "deploymentVersionVarName": If you use environment variables for the configuration of the version of the build that your Jenkins job is running, you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the version. It is mandatory to give a version, the value can also be given in the local configuration of the jobs.
• "settings": In this array settings for several pipelines can be bundled.
• • "pipelines": This array is filled with the names of the pipelines/jobs, for which the following settings should apply
• • "path": The path to the LeanIX-manifest-YAML-file in your SCM (Git, SVN etc.) for the pipelines or jobs defined under "pipelines"

For Frestyle projects is mandatory to give a path to manifest-file here!

This is an example of a configuration:

{
  "leanIXConfigurations": {
    "deploymentStageVarName": "stage",
    "deploymentVersionVarName": "version",
    "settings": [
      {
        "pipelines": [
          "pipeline1",
          "pipeline2",
		  "job1"
        ],
        "path": "/other/lx-manifest.yml"
      },
      {
        "pipelines": [
          "pipeline3"
        ],
        "path": "/lx-manifest.yml"
      }
    ]
  }
}

2. In the second area, "Job result", you can make the basic setting for all jobs / pipelines, which impact a failure of the LeanIX build step will have for the entire job or the entire pipeline. One of the five options that Jenkins offers as a result can be selected here. If the plugin fails, the selected result is set as the end result of the executed job. The default value for the result is "SUCCESS" which means that a failure of the LeanIX-Plugin does not make the pipeline/job fail.

In addition, an SCM provider (e.g. Git) must be set up correctly for the project and the LeanIX manifest file must be located there under the path that is specified in the central configuration for this job.

In order to add the LeanIX plugin to the project, a corresponding build step must be created. To do this, click in the configuration of the Freestyle project under "Build" on "Add build step" and select "LeanIX Value Stream Management".

In the input mask with the title "LeanIX Value Stream Management" that then appears, fill in the appropriate values ​​or select from the drop-down menus:

• LeanIX-Manifest-Path -readonly- : This field is readonly, it will be filled automatically after the first run of the plugin. This is the path to the manifest file that is specified in the central configuration. If it is not specified, the default will be "/lx-manifest.yml".
• Hostname: Enter the host name for the appropriate LeanIX region in which your workspace is located.
• Maven-Settings-Path: The path to the settings.xml file in your SCM (Git, SVN etc.) for the pipelines or jobs. More details about this attribute is documented under Know How
• Apitoken: Enter the API token that matches the host name or your workspace in this protected field.
• Result in case of failure: Indicate what influence a failure of the LeanIX plugin should have on EXACTLY THIS JOB. If you do not make a selection, the selection of the central configuration is used. If you make a selection, the entry for the central configuration for this job will be overwritten. Before the next restart of Jenkins, the central configuration result setting will not be used again.
• Dependency manager of the SCM: Select which DependencyManager you use for your project. This information is important so that the correct dependencies can be generated from your SCM and integrated into the appropriate factsheet. The LeanIX plugin currently supports NPM, MAVEN and GRADLE.
• Use this LeanIX Build Step: This checkbox indicates whether the LeanIX Build step should be executed or skipped. You can use this to switch it on and off as per job.

     environment {
        stage = "dev"
        version = "1.3.0"
    }

Before adding the LeanIX build step to the pipeline, add a secured credentials environment with the Credentials Binding Plugin, as indicated under Prerequisites. The corresponding line looks like this:

     withCredentials ([usernamePassword (credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]{}

• credentialsID: Use the ID that you used in Jenkins, as described under Setting up secrets in the Jenkins administration.

The step in which the LeanIX plug-in is executed must be within the scope of "withCredentials" so that it can securely access the LeanIX API token and the other information. To configure the LeanIX plugin step you can use the "pipeline Syntax" generator of Jenkins. A pipeline step with a built-in LeanIX plugin looks like this:

    steps {
        withCredentials([usernamePassword(credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]) {
            leanIXMicroserviceIntelligence hostname: host, useleanixconnector: true, dependencymanager: 'GRADLE'
        }
    }

When the configuration of the project or pipeline is complete, the start of a build (Build now) will include the execution of the LeanIX plug-in. After execution and if the LeanIX plug-in step has been reached, there is a menu item called "LeanIX Value Stream Management Log" in the monitoring area of each build (click on the build number in the Pipeline or Project area). In this area you will find the information which values were used for the build by the LeanIX plugin as well as information on the result of the step in the "Status" section. Possible errors will be mentioned here.

The plugin also logs information in the "Console Output" section, which is present with every build.

Follow Maven official documentation for more details about the settings file

Following is an example maven settings file present in a GitHub repository.

Ensure to provide the values of id, username, password directly in the file i.e Environment variables cannot be embedded into this during run-time

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>custom-server</id>
            <username>username</username>
            <password>password</password>
        </server>
    </servers>
<!--...-->
</settings>

    steps {
        withCredentials([usernamePassword(credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]) {
            leanIXMicroserviceIntelligence hostname: host, useleanixconnector: true, dependencymanager: 'MAVEN', mavensettingspath: './settings.xml'
        }
    }