Skip to end of metadata
Go to start of metadata

Connecting your Jenkins server to ALM Octane enables you to track and analyze builds, automated test results, and SCM data as part of your product and release quality analysis. For more details, see the ALM Octane Help Center.

Supported plugins

If you have these Jenkins plugins, ALM Octane supports them:

  • MultiJob Plugin 1.15 or later
  • Maven Plugin 2.5 or later
  • Parameterized Trigger Plugin 2.25 or later
  • Matrix Job Plugin 1.4 or later
  • Pipeline Plugin (enabling Pipeline as Code). ALM Octane creates a single pipeline step for each Jenkins job. Steps and stages inside a job are not recognized.

Notes:

  • If you are working with ALM Octane, make sure that you work with version 5.1 or later of this plugin, and that you do not have the ALM Octane CI plugin installed. For more details, see Upgrade from the ALM Octane CI plugin to this plugin.
  • For ALM Octane-UFT integration, make sure that you work with version 5.2 or later of this plugin and with UFT 12.50 or later. 
  • For ALM Octane to collect Performance Center test results from pipeline runs, make sure that you work with version 5.2 or later of this plugin.
  • ALM Octane can display a pipeline's structure only if it is built using one of the following:
    • The built-in Jenkins upstream/downstream mechanism
    • The Multijob plugin
    • The Parameterized plugin

Prerequisites

  1. Java version 8 or higher. To verify your Java version, go to http://www.java.com/en/download/installed.jsp.
  2. ALM/Quality Center client installed the machine that will run the tests. To check if you have a client installed, follow the instructions on this page:   http://<your_server>:8080/qcbin/TDConnectivity_index.html
  3. For running UFT tests from ALM install the ALMClient in common registration mode by accessing the following link from an Internet Explorer browser on the UFT machine: http://<almserver>:8080/qcbin/start_a.jsp?Common=true
  4. For running file system scenarios with LoadRunner or UFT you need to set up a node in Jenkins. For details, see Create an execution node.
  5. For building and tracking pipelines on ALM Octane:
    • JQuery Plugin 1.7.2-1 or later (Required to enable the integration)
    • A plugin that enables publishing test results. For example, JUnit Plugin 1.10 or later, NUnit plugin, and so on (Required to enable ALM Octane to collect your automated test results.)
  6. For ALM Octane integration with UFT:
    • Jenkins Git plugin (version 2.4.4 or later)

Upgrading to the Micro Focus Application Automation Plugin

If you already set up your CI server to work with ALM Octane using the ALM Octane CI plugin, perform the following steps to start using the Micro Focus Application Automation Tools plugin instead:

  1. Go to the Jenkins Server home page.
  2. Click the Manage Plugins link in the left pane. 
  3. Select the Installed tab and uninstall the ALM Octane CI plugin.
  4. Restart Jenkins.
  5. Install the Jenkins plugin, version 5.1 or later.
  6. Restart Jenkins.
  7. Configure the Connection to your ALM Octane Server (below).
  8. To enable the plugin to work with existing ALM Octane pipelines:
    In the ALM Octane CI configuration section, click Show plugin instance ID. In the Instance ID box, enter the Instance ID used by your pipelines in ALM Octane (ALM Octane: Settings > DevOps > CI serversInstance ID column.

Configure the connection to your ALM Octane Server

You must configure this connection if you want to do the following:

  • Create ALM Octane pipelines to track your Jenkins server activity in ALM Octane
  • Configure a testing tool connection in ALM Octane to set up ALM Octane-UFT integration.

Before you configure the connection

  1. Ask the ALM Octane shared space admin for an API access Client ID and Client secret. The plugin uses these for authentication when
    communicating with ALM Octane. The access keys must be assigned the CI/CD Integration role in all relevant workspaces. For details, see Set up API access for integration.
  2. If your network requires a proxy to connect to the Internet, set up proxy configuration.
    1. Go to Manage Jenkins > Manage Plugins > Advanced and define the necessary HTTP Proxy Configuration details:
      • If the ALM Octane server is located outside of the Jenkins server's private network, define the proxy server's details to enable Jenkins to communicate with ALM Octane.
      • If the ALM Octane server and the Jenkins server are both in the same private network (common if you are using ALM Octane on premises), instruct Jenkins not to use the proxy to reach ALM Octane: Add ALM Octane's URL to the No Proxy Host list (using ALM Octane's Fully Qualified Domain Name (FDQN)).
        Note: In this case, you may still need the proxy server details defined to enable Jenkins to access other external resources, such as Git.
    2. Test that Jenkins can now reach ALM Octane:
      Click the Advanced button beneath the HTTP Proxy Configuration details.
      Enter ALM Octane's URL (using its FQDN) and click Test URL.
    3. Restart the Jenkins server so the plugin uses the new proxy settings.
  3. Decide which Jenkins user ALM Octane will use to execute jobs on the server.
    Caution: We strongly recommend setting this user’s permissions to the minimum required for this integration.
    The Jenkins user must have the following permissions:
    • For working with ALM Octane pipelines: Job Build.
    • For ALM Octane-UFT integration: Job Create, Delete, and Read.
      If your Git repository requires credentials, Credentials create and update permissions are also required.

Configure the connection

  1. Go to the Jenkins Server home page.
  2. Click the Manage Jenkins link in the left pane.
  3. Click Configure System.
  4. Scroll down to the ALM Octane CI section.
  5. Click Add ALM Octane server.
  6. Follow the instructions on the screen to complete the configuration:
    • For Location, enter the URL of the ALM Octane server, using its fully
      qualified domain name (FQDN). Use the following format (port number is optional):
      http://<ALM Octane hostname / IP address> {:<port number>}/ui/?p=<shared space ID> 
      For example, in this URL, the shared space ID is 1002: http://myServer.myCompany.com:8081/ui/?p=1002 
      Tip: You can copy the URL from the address bar of the browser in which you opened ALM Octane.
    • When entering the Client ID and Client secret, make sure to enter the exact text without leading or trailing spaces.
    • For Jenkins user, enter the Jenkins user ALM Octane will use to execute jobs on the server.
      Make sure the user can log in to Jenkins and has the minimum permission required for this integration: Job Build permissions. 
      We strongly recommend specifying a Jenkins user for ALM Octane. If you do not specify a Jenkins user, ALM Octane uses the Anonymous user, and is limited to the Anonymous user permissions.
  7. To connect additional ALM Octane shared spaces, click Add ALM Octane server and enter details.
  8. Click Test Connection to validate the configuration.
  9. Click Submit to save your changes.

After the connection is set up you can do any of the following

  • Create ALM Octane pipelines from the ALM Octane user interface. To do this, define a CI server in the ALM Octane settings and then create pipelines. For details, see Integrate with your CI server.
  • Create ALM Octane pipelines from the Jenkins user interface. For details, see Create and configure ALM Octane pipelines on Jenkins.
  • Set up ALM Octane integration with UFT. To do this, define a CI server in the ALM Octane settings and then create a testing tool connection. For details, see Set up UFT integration.
  • Set up a security integration with Fortify Software Security Center (SSC), to display data on vulnerabilities using ALM Octane. For details, see Set up an integration with Fortify.
     

Create and configure ALM Octane pipelines on Jenkins

Before you can create an ALM Octane pipeline, make sure you have configured the connection to your ALM Octane server (above).

To create an ALM Octane pipeline in Jenkins:

  1. Go to the Jenkins Server home page.
  2. Click on the job that you want to use as the root job for your pipeline.
    Note: Select a job that is not already part on an existing ALM Octane pipeline.
  3. In the menu in the left pane, click ALM Octane Pipelines.
  4. Click Create Pipeline.
  5. Enter the details for the pipeline:
    1. Provide a name for the pipeline. The Workspace list displays all of the workspaces on the ALM Octane server you configured in the ALM Octane CI section.
    2. Select a workspace for your pipeline.
    3. The Release list displays the releases available in the workspace you selected.
      Optionally, select a release to associate with your pipeline.
  6. Click Create.
    Caution: If you delete a pipeline, all its labels and configuration information are lost.


To edit the pipeline and configure pipeline steps:

  1. Go to the Jenkins Server home page.
  2. Click on a job that is included in an existing ALM Octane pipeline.
  3. In the menu in the left pane, click ALM Octane Pipelines. The page for editing pipelines opens.
  4. You can edit the pipeline’s name, workspace, or release.
  5. For a job that runs tests, configure test and environment details. For details, see Create and configure pipelines.
    Note:
    • A Jenkins job may be included in a pipeline more than once. When you configure a Jenkins job, this affects all of the relevant steps in the ALM Octane pipeline.
    • To dynamically set environment tags during the build run, based on build parameter values, configure the pipeline in ALM Octane.
  6. Click Apply.


For details on tracking your pipelines in ALM Octane, see Run and analyze pipelines.

Troubleshoot the Jenkins-ALM Octane Integration

If you are working with version 5.1 or later of this plugin, make sure you do not have the old ALM Octane Plugin installed on your Jenkins server.

In addition, here are some suggested solutions for issues you might encounter:

  • Issue: Cannot run pipelines from ALM Octane. The Run button is disabled.
    Possible solutions:
    • The Jenkins server might be down, or it is not communicating with ALM Octane.
    • If this occurred after upgrading from the ALM Octane Plugin: Make sure that in the plugin's ALM Octane CI configuration, you updated the Instance ID with the ID defined in ALM Octane for the CI server. For details, see Upgrade from the ALM Octane CI plugin to this plugin
       
  • Issue: When creating a new pipeline in ALM Octane, the message "Failed to fetch Jenkins job" is displayed in the Job field after you select a CI server.
    Possible solutions:
    • This happens when a Jenkins job indirectly calls itself. Try creating the pipeline from Jenkins. In this case, the log files do not indicate any problem.
      Version 5.2 of this plugin introduced a fix for this issue.
    • See "Errors occur when ALM Octane requests something from Jenkins".
       
  • Issue: Errors occur when ALM Octane requests something from Jenkins.
    When running a pipeline from ALM Octane, the error message is displayed: "Run pipeline: an Error occurred while running the pipeline”
    When creating a new pipeline in ALM Octane, the message "Failed to fetch Jenkins jobs - Error 403 forbidden" is displayed in the Job field after you select a CI server.
    Solution: This is an issue with the permissions of the Jenkins user that ALM Octane uses to execute jobs on the server.
    In the Jenkins configuration, in the ALM Octane CI section define a Jenkins user. This user must have Job Build permissions.
    For details, see Configure the Connection to your ALM Octane Server.
     
  • Issue: When creating a new CI server in ALM Octane, the Jenkins server is not displayed in the list of connected servers even though Test Connection on Jenkins worked.
    Solution: Make sure that the Jenkins proxy settings are correct and that you restarted the Jenkins server after changing proxy settings. For details, see Configure the Connection to your ALM Octane Server.
     
  • Issue: Test results from the pipelines are not reflected in ALM Octane.
    Solution: Test results from Maven jobs are not reported to ALM Octane if the job is under a folder. Free style and pipeline jobs report results as expected.
    Version 5.2 of this plugin introduced a fix for this issue.

Using log files to troubleshoot
Jenkins sends various events and data to ALM Octane. For example: Start job, Finish job, SCM data, test results.
When an error occurs, check the communication between Jenkins and ALM Octane.
To help troubleshoot, you might want to check the log file on the Jenkins server for connectivity issues, security issues, and so on.

The log files are located in the following locations: 
Jenkins system logs: http://<Jenkins url>/log/all
Plugin logs: http://<Jenkins url>/userContent/nga/logs/nga.log

Understanding the plugin's log messages

  • At the end of a successful flow, Jenkins sends: done, left to send 0 events
    For example: 
    INFO - EventsClient: sending events [job\-name:STARTED] to 'http://localhost:8080'...
    INFO - EventsClient: sending events [job\-name:FINISHED] to 'https://mqast010pngx.saas.mf.com'...
    INFO - EventsClient: ... done, left to send 0 events
    INFO - TestDispatcher: There are pending test results, connecting to the MQM server
    INFO - TestDispatcher: Successfully pushed test results of build job-name#10
  • When the ALM Octane server is not available, log messages may look like this:
    ERROR - BridgeClient: connection to MQM Server temporary failed: authentication error com.hp.mqm.client.exception.AuthenticationException: Authentication failed: code=503; reason=Service Unavailable
  • When an error occurs in the Jenkins -> ALM Octane communication, log messages may look like this:
    ERROR - EventsClient: max number of retries reached
    TestDispatcher: There are pending test results, but we are in quiet period


Troubleshoot Creating and Configuring ALM Octane Pipelines

  • Issue: Error when trying to create a pipeline:


    Unable to create pipeline


    Solution: Make sure the workspace you selected is included in the list of workspaces defined for the access keys that you used to

    connect the ALM Octane CI to ALM Octane.

    If you still encounter an error, select a different workspace, or ask an ALM Octane shared space admin to add the workspace to the list. For details, see Set up API access for integration.

  • Issue: Error when trying to configure a job:


    Unable to retrieve job configuration


    Solution: The pipeline containing this job might have been created in ALM Octane in a workspace that is not accessible from the ALM Octane CI plugin. 
    Make sure that the workspace is included in the list of workspaces defined for the access keys that you used to connect the ALM Octane CI to ALM Octane. 
    If you still encounter an error, ask an ALM Octane shared space admin to add the workspace to the list. For details, see Set up API access for integration.
  • No labels