Jenkins integration

Integration with Jenkins enables you to incorporate data from your Jenkins CI pipelines into your application delivery process.

Note: For details on integrating a non-Jenkins CI server, see CI server integration.

Plugin overview

The Application Automation Tools CI plugin enables integrating with a CI server.

The CI plugin provides the following capabilities:

  • Retrieve and display the build pipelines that run on the CI server

  • Trigger pipeline runs on the CI server

  • Retrieve build run results, test run results, and commit information from the CI server

  • Retrieve code coverage reports from a Jenkins CI server

  • Trigger OpenText Functional Testing test runs on a Jenkins CI server

Note: To integrate with Jenkins, do not install the CI plugin on the Jenkins server. For details, see Upgrade to the Application Automation Tool plugin.

Back to top

Supported plugins

You connect to your Jenkins server using the Application Automation Tools plugin. You can then track and analyze builds, automated test results, and SCM data.

For the latest list of plugin dependencies, see Dependencies.

Follow these guideline when preparing the Jenkins integration:

  • Make sure that you work with Application Automation Tools plugin version 5.1 or later, and that you do not have the OpenText Core Software Delivery Platform CI plugin installed. For more details, see Install or upgrade the plugin.

  • For OpenText Functional Testing integration, make sure that you work with Application Automation Tools plugin version 5.2 or later, and with OpenText Functional Testing 12.50 or later.

  • To collect LoadRunner Enterprise test results from pipeline runs, make sure that you work with Application Automation Tools plugin version 5.2 or later. For details, see LoadRunner Enterprise.

  • A pipeline's structure can only be displayed if it is built using one of the following:

    • The built-in Jenkins upstream/downstream mechanism

    • The Multijob plugin

    • The Parameterized plugin

Back to top

Prerequisites

Make sure you meet the necessary requirements.

  • For setting up an integration with a CI server, see CI integration prerequisites.

  • For integrating with Jenkins, see the prerequisites below.

    Prerequisite Details
    Java version 8 or later Verify your Java version.
    ALM/Quality Center client The ALM/Quality Center client must be installed on the machine that runs the tests. To check if you have a client installed, follow the instructions on this page: http://<your_server>:8080/qcbin/TDConnectivity_index.html.
    Node in Jenkins

    For running file system scenarios with OpenText Functional Testing, set up a node in Jenkins. For details, see Create an execution node.

    JQuery Plugin and a plugin for publishing test results

    For building and tracking pipelines, install the following:

    • 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, or NUnit plugin (required to enable collection of your automated test results).
    Jenkins Git plugin

    For integration with OpenText Functional Testing, install Jenkins Git plugin (version 2.4.4 or later).

Back to top

Install or upgrade the plugin

In your Jenkins server's user interface, open the plugin management area and upload the Application Automation Tools plugin.

To install the plugin:

  1. Go to the Jenkins Server home page.

  2. Click Manage Jenkins.

  3. Click Manage Plugins, select the Advanced tab, and scroll down to Upload Plugin.

  4. Browse to the plugin file that you downloaded and click Upload.

  5. Select the option to restart Jenkins when installation is complete and no jobs are running.

Note: If you activate or deactivate the plugin at any time after installation, you must restart your CI server.

Upgrade to the Application Automation Tool plugin

If you are currently using the OpenText Core SDP CI plugin, you must remove it and replace it with the Application Automation Tools plugin.

  1. Go to the Jenkins Server home page.

  2. Click the Manage Plugins.

  3. Select the Installed tab and uninstall the OpenText Core SDP CI plugin.

  4. Restart Jenkins.

  5. Install the Application Automation Tools plugin, version 5.1 or later.

  6. Restart Jenkins.

Back to top

Configure the connection

This section describes how to set up the connection to the Jenkins machine.

Before you configure the connection:

  1. Ask the shared space admin for an API access client ID and client secret. The plugin uses these for authentication when communicating with OpenText Core SDP. The access keys must be assigned with the CI/CD Integration role in all the relevant workspaces. For details, see API access.

  2. If your network requires a proxy to connect to the Internet, set up the proxy configuration.

    Action Details
    Define the HTTP Proxy Configuration

    Go to Manage Jenkins > Manage Plugins > Advanced and define the necessary HTTP Proxy Configuration details.

    • If the OpenText Core SDP server is located outside of the Jenkins server's private network: Define the proxy server's details to enable Jenkins to communicate with OpenText Core SDP.

    • If the OpenText Core SDP server and the Jenkins server are both in the same private network (common if you are using OpenText Core SDP on‑premises): Instruct Jenkins not to use the proxy to reach OpenText Core SDP.

      To do this, add the OpenText Core SDP URL to the No Proxy Host list using its Fully Qualified Domain Name (FQDN).

      Note: You might still need the proxy server details defined to enable Jenkins to access other external resources, such as Git.
    Test connection

    Click the Advanced button beneath the HTTP Proxy Configuration details. Enter OpenText Core SDP's URL using its Fully Qualified Domain Name (FQDN), and click Test URL.
    Restart the Jenkins server Restarting is necessary for the plugin to use the new proxy settings.

  3. Decide which Jenkins user should be used to run jobs on the server.

    Caution: We recommend that you set this user’s permissions to the minimum required for this integration. The Jenkins user must have the following permissions:

    • Job Build: For working with OpenText Core SDP pipelines

    • Job Create, Delete, and Read: For OpenText Functional Testing integration

    • Credentials create and Update: If your Git repository requires credentials

Configure the connection

To set up the connection to Jenkins:

  1. Go to the Jenkins Server home page.
  2. Click the Manage Jenkins link.
  3. Click Configure System.
  4. Scroll down to the OpenText Core Software Delivery Platform CI section.
  5. Click Add OpenText Core Software Delivery Platform server.

  6. Follow the instructions on the screen to complete the configuration.

    Field Details
    Location

    Enter the URL of the OpenText Core SDP server using its fully qualified domain name (FQDN).

    Use the following format:

    http://<OpenText Core SDP 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

    If the port is 80, you do not need to add the port number.

    You can copy the URL from the address bar of the browser in which you opened OpenText Core SDP. For example, if this is your workspace URL, copy the full address: 

    https://almoctane.saas.microfocus.com/ui/?p=100101/1002#/

    Client ID and Client secret

    Make sure to enter the exact text without leading or trailing spaces.
    Jenkins user

    • Enter the Jenkins user that OpenText Core SDP should use to run 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.

      Note: We recommend that you specify a Jenkins user for OpenText Core SDP. If you do not specify a Jenkins user, OpenText Core SDP uses the Anonymous user, and is limited to the Anonymous user permissions.

    • In some environments, you might want users in OpenText Core SDP to only have access to a subset of jobs in specific workspaces. To define a user in Jenkins that only has access to a subset of jobs, click Advanced, and enter one or more sets of users per workspace in the Jenkins user for specific workspaces box. When creating a pipeline, you only see the jobs that can be accessed by the Jenkins user assigned to the current workspace. For details, see the plugin help.
  7. To connect additional shared spaces, click Add OpenText Core Software Delivery Platform server and enter the details.
  8. Click Test Connection to validate the configuration.
  9. Click Submit to save your changes.

Post setup actions

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

Back to top

Move an existing CI server to a new address

If you move your Jenkins server and reinstall the plugin, use the following steps to adjust the plugin's configuration and continue working with your existing pipelines.

To configure the Jenkins plugin to work with existing pipelines:

  1. Get the plugin instance ID originally used to set up the CI server on OpenText Core SDP:

    1. Open the Settings menu , click Spaces, and select a workspace.

    2. Open the DevOps tab, and select CI servers.

    3. In the grid, locate the Instance ID column and copy your CI server's Instance ID.

  2. In Jenkins, update the new plugin to use the original instance ID.

    1. Click Manage Plugins.

    2. Click Configure System.

    3. Scroll down to the ALM Octane CI configuration area.

    4. Click Show plugin instance ID.

    5. In the Instance ID box, enter the Instance ID you copied in the previous step.

Back to top

Create and configure pipelines on Jenkins

Before you can create a pipeline, make sure that you have configured the connection to your OpenText Core SDP server. For details, see Configure the connection.

To create a pipeline in Jenkins:

  1. Go to the Jenkins Server home page.

  2. Click 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 pipeline.

  3. In the menu, click OpenText Core Software Delivery Platform Pipelines.

  4. Click Create Pipeline.

  5. Select the configuration of the OpenText Core SDP server configured in Jenkins.

  6. Enter the details for the pipeline.

    1. Provide a name for the pipeline.

    2. Select a workspace for your pipeline. The list displays all the workspaces on the OpenText Core SDP server that you configured in the OpenText Core SDP CI section.

    3. (Optional) Select a release to associate with your pipeline. The release list displays only the releases available in the workspace you selected.

    4. (Optional) Select a milestone to associate with your pipeline. The milestones list displays only the milestones available in the release you selected.

  7. 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 a job that is included in an existing pipeline.

  3. In the menu, click OpenText Core Software Delivery Platform Pipelines. The page for editing pipelines opens.

  4. You can edit the pipeline’s name, workspace, release, or milestone. If you change a milestone or release, a new set of runs is created on OpenText Core SDP, with a new run history.

  5. For a job that runs tests, configure test and environment details. For details, see Create and configure pipelines.

    Note:

    • A Jenkins job can be included in a pipeline more than once. When you configure a Jenkins job, this affects all of the relevant steps in the pipeline.

    • To dynamically set environment tags during the build run, based on build parameter values, configure the pipeline in OpenText Core SDP.

  6. Click Apply.

For details on tracking your pipelines, see Run pipelines.

To configure a pipeline with parameterized tests (optional):

  1. If your tests are parameterized, each run result is displayed as a separate test. To see run results under a single test with a separate run for each parameter value, add a parameter to your pipeline job called octane_test_result_name_run_regex_pattern.

  2. Define its value using a regular expression which splits the test name into two parts; one to be used as the test name, and the other (representing the parameter value) to be used as the external run ID.

    Example: If your test uses the format Test name [parameter1,parameter2], define the regex as \[,*\]

  3. When you run the pipeline with parameters, define the parameter name as octane_test_result_name_run_regex_pattern. Define its value as the regex you defined in the job.

    Example: In the above example, the result is two test runs whose name is the test name, and whose external run IDs are parameter1 and parameter2.

Back to top

Trigger suite runs from Jenkins

You can use automated test execution modes in the Jenkins plugin to enable Jenkins to trigger suite runs. This can be useful in a number of scenarios. For example:

  • Defining a schedule in Jenkins, if you do not use Functional Test Execution.

  • Triggering suite runs from an auto action in a release process.

  • Triggering suite runs as a step in a bigger pipeline.

The following automated test execution modes are available.

Mode Description
Suite context

You provide suite IDs. The Jenkins job creates a suite run for each one, and triggers the test runs as if you ran the suite from OpenText Core SDP.

The job does not need to be defined as a pipeline in OpenText Core SDP. To see and analyze results, go to the suite run.

Pipeline context

You provide suite IDs. The Jenkins job fetches all tests from the selected suites. The job runs them by triggering the correct sub-job based on the assigned test runner.

The job should be defined as a pipeline in OpenText Core SDP. To see and analyze results, go to the Pipeline module.

For details, see Application Automation Tools.

Back to top

Troubleshoot the Jenkins integration

If you are working with Application Automation Tools plugin version 5.1 or later, make sure that you do not have the old OpenText Core SDP CI plugin installed on your Jenkins server.

The following table provides suggestions for solving integration issues:

Issue Possible solutions
Test Connection fails

Verify that you are not using an outdated sdk version of the CI plugin.
Cannot run pipelines from OpenText Core SDP. The Run button is unavailable.

  • The Jenkins server might be down, or it is not communicating with OpenText Core SDP.

  • If this occurred after upgrading from the CI  Plugin: Make sure that in the plugin's OpenText Core SDP CI configuration, you updated the Instance ID with the ID defined in OpenText Core SDP for the CI server.
When creating a new pipeline in OpenText Core SDP, the message "Failed to fetch Jenkins job" is displayed in the Job field after you select a CI server.

  • 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 the next issue, "Errors occur when OpenText Core Software Delivery Platform requests something from Jenkins".

Errors occur when OpenText Core SDP requests something from Jenkins.

  • When running a pipeline from OpenText Core SDP, the message "Run pipeline: an Error occurred while running the pipeline” is displayed.

  • When creating a new pipeline in OpenText Core SDP, the message "Failed to fetch Jenkins jobs - Error 403 forbidden" is displayed in the Job field after you select a CI server.

This is an issue with the permissions of the Jenkins user that OpenText Core SDP uses to execute jobs on the server.

In the Jenkins configuration, in the OpenText Core SDP CI section, define a Jenkins user. This user must have Job Build permissions.

When creating a new CI server in OpenText Core SDP, the Jenkins server is not displayed in the list of connected servers even though Test Connection on Jenkins worked.

Make sure that the Jenkins proxy settings are correct and that you restarted the Jenkins server after changing proxy settings. For details, see CI integration prerequisites.
Test results from the pipelines are not reflected in OpenText Core SDP.

Test results from Maven jobs are not reported if the job is under a folder. Version 5.2 of this plugin introduced a fix for this issue.

Free style and pipeline jobs report results as expected.

Using log files to troubleshoot

Jenkins sends various events and data to OpenText Core SDP. For example, Start job, Finish job, SCM data, and test results.

When an error occurs, check the communication between Jenkins and OpenText Core SDP.

Also check the log file on the Jenkins server for connectivity and security issues.

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 OpenText Core SDP 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–OpenText Core SDP 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

Back to top

Troubleshoot creating pipelines

Use this table to solve your integration issues.

Issue Possible solutions
Error when trying to create a pipeline: Unable to create pipeline

Make sure that the workspace you selected is included in the list of workspaces defined for the access keys that you used to connect the OpenText Core SDP CI to OpenText Core SDP.

If you still encounter an error, select a different workspace, or ask a shared space admin to add the workspace to the list. For details, see API access.
Error when trying to configure a job: Unable to retrieve job configuration

The pipeline containing this job might have been created in a workspace that is not accessible from the 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 OpenText Core SDP CI to OpenText Core SDP.

If you still encounter an error, ask a shared space admin to add the workspace to the list. For details, see API access.

Back to top

See also: